INSIDE LEVEL II 


A PROGRAMMER’S GUIDE 
TO THE TRS-80® ROMS 



Mumford Micro Systems 




















PREFACE 


(TRS—80 is a trademark of the Tandy Corporation.) 

The TRS—80 is a capable machine, particularly so if it is programmed in its own (Z—80) assembly lan¬ 
guage. Assembly language programming is greatly facilitated by having a collection of general routines to 
draw upon. Your Level If ROM contains many useful routines, and one of the principal aims of this book is to 
provide the information necessary for utilizing these routines in your own assembly language programs. In 
Part I of the book, you will learn the locations of these routines, the optimum entry points for minimizing 
their calling sequences, and the setups and assembly language instructions required to call them. In addition, 
approximate execution times for the arithmetic and function routines are given. 

The second main objective of this book is to detail an efficient scheme for linking assembly language and 
BASIC programs. The result can be a single, smoothly joined program that combines the best features of both 
languages — the ease of writing, string capability, and input—output power of BASIC, together with the 
speed of execution of assembly language. It is not atypical for 25% of a given program (written wholly in 
BASIC) to require 95% of the operating time. If this time—critical part can be rewritten in assembly language 
and efficiently linked to the remainder of the BASIC program, one can enjoy the best of both worlds. Part II of 
this book tells how to achieve an efficient linkage. 

To take full advantage of the information in this book requires a knowledge of Z—80 assembly language 
programming. Readers with such knowledge who are also fortunate enough to own a TRS—80 without a disk 
should experience little difficulty in putting this information to immediate use. The presence of a disk compli¬ 
cates matters, principally because the Level II ROM has exits to DISK BASIC that are not always plugged up 
when the latter is not present, and also because there are (and will be) different versions of disk system 
software. Nevertheless, all the material of this book can be used with disk systems provided sufficient care is 
taken, and the book details exactly where and how special allowances for a disk need to be made. 


The information presented in this work is not theoretical. It is the result of direct experience and use by the 
authors, and is true and correct to the best of our knowledge. Mumford Micro Systems does not, however, 
assume any liability for the reliability of this information, or for any losses incurred through its use or 


misuse. 
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INTRODUCTION 


A. Representation of Numbers in TRS-—80 

Both decirhal and hexadecimal numbers will be employed in the explanations in this book. All memory 
addresses, and the contents of registers and memory cells, will be given in hexadecimal, with a postfixed H. 
Decimal numbers will be used in most other situations; where ambiguity might arise, decimal numbers will 
be distinguished by the legend "(decimal)". Pages 8/9 and 8/10 of the Level II Basic Reference Manual 
have brief descriptions of the internal representations of numbers in the TRS—80. It is the purpose of this 
section to expand upon those descriptions. 

A number may be represented in the TRS—80 in one of three different formats: integer, single precision, 
or double precision. (There is also a 16—bit positive integer format for addresses and line numbers that is 
discussed in Section 3.3 (b).) 

An integer is stored in two consecutive bytes of memory, or held in a register pair (BC, DE, or HL). The 
more significant byte is stored in the memory cell with the higher address, or in the B, D, or H register of a 
register pair. (Observe that the usual order of the bytes is reversed in memory storage. That is, the less 
significant byte, which would be written last in ordinary notation, will be the first to appear in a memory scan 
that proceeds in order of increasing addresses. The reason for this is that the Z—80 architecture requires it.) 
Bit 7 (the leftmost, or most significant bit) of the more significant byte is the sign bit: 0 for a positive integer, 
1 for a negative integer. The largest positive integer that can be represented (a 0 sign bit followed by fifteen 1 
bits) is thus 32767. 

Negative integers are stored in two's complement form. Bit 7 of the more significant byte is 1. To find the 
absolute value of a negative integer, complement all the bits and add 1 to the resulting number. The absolute 
value of a negative integer cannot exceed 32768. 

EXAMPLE: DA5CH represents a negative integer. To find out what negative integer it represents, first 
complement all bits by subtracting it from FFFFH: FFFFH — DA5CH = 25A3H. Then add 1: 
25A3H + 1 = 25A4H. Since 25A4H represents 9636 (decimal), the original hexadecimal number 
represents —9636. 

A number in single precision format is stored in four consecutive bytes of memory, or in two register pairs. 
The first byte (stored in the memory cell with the highest address) contains the exponent (on base 2) in excess 
128 format. That is, the true exponent is 128 (decimal) less than the number represented by the exponent 
byte. (All bits in the exponent byte have their normal meaning; thus, the exponent byte can represent any 
integer from 0 to 255, inclusive.) 

EXAMPLES: An exponent byte of CFH represents an actual exponent of 79 (decimal), because CFH = 207 
(decimal), and 207 — 128 = 79. Likewise, an exponent byte of 3DH represents an actual 
exponent of —67 (decimal), because 3DH = 61 (decimal), and 61 — 128 = —67. 

In single precision format, an exponent byte of 0 is used to signify the number 0, in which case the 
remaining three bytes have no effect upon the processing of the number. Otherwise (that is, exponent byte 
not 0), the remaining three bytes (called the mantissa) are assumed to have a binary point in front of the most 
significant bit (bit 7 of the most significant byte of these three). (Again, the significance of the bytes increases 
with increasing memory addresses, so that the bytes of a single precision number will appear in memory to be 





reversed from their "natural" order.) Also, it is assumed that the most significant bit is a 1, so that the 
mantissa of any nonzero single precision number always represents a fraction greater than or equal to 1/2 and 
smaller than 1. (This is normalized floating point representation.) The mantissa is, of course, to be multiplied 
by 2 to the power of E — where E is the true exponent (exponent byte less 128) — to get the single precision 
number represented. 

Since the most significant bit of the mantissa is always assumed to be 1, the actual most significant bit is 
free to be used as a sign bit (0 for +, 1 for —). This device allows the representation of numbers with one 
more bit of precision than if a separate bit were provided foF the sign. 

A positive single precision number and its corresponding negative number are represented in exactly the 
same way except for the sign bit (bit 7 of the second byte). There is no two's complement form as there is in 
integer representation. 

EXAMPLES: (In these examples the four bytes of each single precision number are given in hexadecimal, 
with the exponent byte first, the most significant byte of the mantissa second, and the least significant byte 
last.) 

(a) 82H, 40H, 0, 0 represents 2 to the power of 2 multiplied by .110000000000000000000000 (the mantissa 

being given in binary), or 3.0 (decimal). Note the 1 supplied immediately after the binary point; this 
is automatic. The 1 in the second position following the binary point comes from the40H expressed 
in binary. 

(b) 82H, COH, 0, 0 represents —3.0 (decimal). Here the minus sign occurs because the second byte has a 1 in 

bit 7; this 1 becomes the (negative) sign, and a new 1 is then automatically supplied for the man¬ 
tissa. 

(c) Let’s analyze the single precision number represented by 84H, 67H, 80H, 0. First, the exponent byte 

(84H) represents a true exponent of 4, since 84H = 132 (decimal), and 132 — 128 = 4. Next, the 
most significant bit of the mantissa is 0, since 67H has 0 in its leftmost bit position. Therefore, the 
number represented is positive. Now, 67H is 01100111 in binary, and the bytes following it (80H, 
0) expand this to binary 


0110 0111 1000 0000 0000 0000 
Next we supply the automatic 1 in the most significant bit: 

mo oin iooooooooooooooo 

The exponent 4 means that the binary point is placed between the 4th and 5th bits from the left: 

1110.0111 1000 0000 0000 0000 
Drop the trailing zeroes to get 

1110.01111 

This is equai to 8 + 4 + 2 + 0 + 0/2 + 1/4 + 1/8 + 1/16 + 1/32 = 14 + 15/32 = 14.46875 (decimal). 
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Converting decimal numbers to single precision format is a necessary operation for assembly language 
programming of arithmetic procedures, but the above discussion and examples may have dampened your 
enthusiasm for such conversions. If so, you may use routines in the Level II ROM to perform the conver¬ 
sions; methods for doing this will be given in Section 3.4 (a). 

A number in double precision format is stored in eight consecutive bytes of memory. This format is 
identical to single precision format except that the mantissa has four additional (low order) bytes of precision. 
(Again the bytes will appear in memory in the reverse of "natural" order.) Just as in single precision format, 
nonzero numbers with absolute values in the range of 2 to the power of —128 to 2 to the power of +127 can 
be represented. 


B. Use of Registers 

Using the Z—80 registers for temporary storage of characters, one and two byte integers, and addresses can 
be extremely effective in minimizing the size and execution time of an assembly language program. Almost 
all of the ROM subroutines described in this book use the registers for their own purposes without saving and 
restoring their contents. It follows that you should not expect any register to be returned with its contents 
intact after a call to a ROM subroutine. If you wish to save a register (pair), PUSH it onto the stack before the 
subroutine call and POP it off again after the return. 


C. Links to DISK BASIC 

A number of ROM subroutines contain calls to addresses in reserved RAM. In diskless systems, these 
RAM addresses hold subroutine returns that immediately terminate the calls. In a system with a disk, how¬ 
ever, these RAM addresses may hold jumps to DISK BASIC enhancement routines. As long as DISK BASIC 
is present when your assembly language program uses these ROM subroutines, there will be no problem. 
However, if you read your assembly language program from disk and execute it directly, DISK BASIC may 
not be present, and the "leaks" from reserved RAM to DISK BASIC may not be plugged. The result can be a 
random jump, necessitating a reinitialization of DOS. There are two ways to avoid this embarrassment. One 
is to make sure that DISK BASIC is present before running your assembly language program that uses ROM 
subroutines; this can be done by employing the LOAD command to read the program from disk, then trans¬ 
ferring to BASIC and using the SYSTEM command to commence execution of the program. The other 
methocT is for your assembly language program to store RETurns (C9H) in the reserved RAM locations that 
are called by the ROM subroutines that it uses. The information that you need to implement this second 
method will be found in subsequent sections; each sensitive subroutine will be indicated, and the RAM 
addresses that need to be plugged will be identified. 

Relatively few of the ROM routines to be described in this book — and none of the conversion, arithmetic, 
or function routines — have direct exits to DISK BASIC. Nevertheless, many routines have the (remote) 
potential of transferring control to the Level II monitor because of operational errors — overflow, divide by 
zero, illegal function call, etc. And the Level II monitor has many exits to DISK BASIC. A blunderbuss 
approach to the problem of "leaks” would be to store RETurns in all RAM locations that might cause trouble. 
A complete list of these addresses is: 400CH and twenty—one locations starting at 41A6H and proceeding in 
steps of 3 (41A6H, 41A9H, 41ACH, etc.). Here is an assembly language segment that you could use at the 
beginning of your assembly language program to store RET's in all the aforementioned locations: 
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LOOP 


LD 

A,0C9H 

LD 

(400CH),A 

LD 

HL.41A6H 

LD 

B,15H 

LD 

(HL),A 

INC 

HL 

INC 

HL 

INC 

HL 

DJNZ 

LOOP 


FINAL NOTE: The transfer point at 400CH is actually an exit to DOS that is taken when the BREAK key is 
depressed. If you store a RET in this location, you should restore the JP (C3H) that is normally there before 
exiting to the operating system. Failure to restore this JP can result in a reinitialization of DOS. 
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PARTI 


The Level II ROM and Reserved RAM 
CHAPTER 1 

Key Locations and Entry Points 

1.1. Reserved RAM Storage Locations 

The TRS—80 memory map on pages D/1 and D/2 of the Level II Basic Reference Manual shows that 
memory locations 4000H through 42E8H are reserved for the use of the Level II monitor. The most signific¬ 
ant of these locations are listed below, together with their functions. 

4016H—4017H: Hold the entry point address of the keyboard driver. 

401 EH—401FH: Hold the entry point address of the video driver. 

4020H—4021H: Hold the video memory address of the current cursor position. 

4026H—4027H: Hold the entry point address of the line printer driver. 

408EH—408FH: Used to hold the entry address of a machine language program called by the USR com¬ 
mand. 

40A0H—40A1H: Hold the address of the start of the string storage area. 

40A4H—40A5H: Hold the starting address of BASIC program text. 

40A7H—40A8H: Hold the beginning address of the keyboard input buffer. 

40AAH—40ACH: Hold the three bytes of seed number for the random number generator. 

40AFH-: Holds a flag indicating the type of the variable being processed by a ROM routine. This flag has 
value 2 for an integer variable, 3 for a string variable, 4 for a single precision variable, or 8 for a 
double precision variable. 

40B1H—40B2H: Hold the MEMORY SIZE (top of the unprotected RAM). 

40DFH—40E0H: Hold the entry point address for a SYSTEM tape that has just been read. (This address 
may be destroyed by execution of a BASIC program.) 

40F9H—40FAH: Hold the starting address of the BASIC simple variable storage area. 
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40FBH—40FCH: Hold the starting address of the BASIC array variable storage area. 

40FDH—40FEH: Hold the starting address of the BASIC free memory area. 

411DH—4124H: Provide a buffer area for a double precision variable to be processed. 

4121H—4122H: Provide a buffer area for an integer variable to be processed. 

4121H—4124H: Provide a buffer area for a single precision variable to be processed. 

4127H—412EH: Provide a buffer area for a second double precision variable to be processed. 

41A9H—41ABH: Here may be stored a machine language jump to a routine that expands the number of 
available USR calls. 

41E8H—42E7H: Provide a buffer area for keyboard input in systems without disks. 


1.2. Entry Points for Level II Commands and Functions 

Table 1.2 shows the ROM entry points for the Level II commands and functions. (Arithmetic operations have 
several entry points each; these entry points will be given in Chapter 4.) 

Many of the subroutines that implement these commands and functions will be described more fully in later 
sections of this book, where the recommended entry points may differ from those presented here. The reason 
for the differences is that the entry points to be given later have been chosen for their efficiency; the locations in 
Table 1.2 are the ones actually used by the Level II monitor. 


1.3. Transfer points for DISK BASIC Commands 

The Level 11 ROM transfers certain DISK BASIC commands to addresses in reserved RAM. In a disk—based 
system, these locations are filled with jumps to DISK BASIC, but in a diskless system the locations are filled 
with jumps to 012DH. (A jump to 012DH causes "?L3 ERROR” to be displayed.) If you have a system with no 
disk, you may thus add new commands to your computer by filling some of these locations with jumps to your 
own assembly language program that implements the new commands. Table 1.3 lists these DISK BASIC 
commands‘and their transfer points in reserved RAM. 

The Z—80 RST instruction is a special one—byte subroutine call to a low memory address. The Level II 
ROM transfers seven of these RST's to addresses in reserved RAM, from which points they are turned back 
into the ROM or transferred again to DISK BASIC. By filling some^of these RAM locations with jumps to 
your own assembly language program, you can provide that program with low—overhead calls to frequently 
used subroutines. (Caution: Use of this technique will disable many ROM subroutines. Be sure that they 
aren't ones that you are using in your assembly language program.) Here are the RST's and their reserved 
RAM transfer points: 


RST 8 

4000H 

RST 28H 

400CH 

RST 10H 

4003H 

RST 30H 

400FH 

RST 18H 

4006H 

RST 38H 

4012H 

RST 20H 

4009H 
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Table 1.2 — Level II Entry Points 


ABS 

0977H 

LIST 

2B2EH 

ASC 

2A0FH 

LLIST 

2B29H 

ATN 

15BDH 

LOG 

0809H 

AUTO 

2008H 

LPRINT 

2067H 

CDBL 

OADBH 

MIDS 

2A9AH 

CHRS 

2A1FH 

MEM 

27C9H 

CINT 

0A7FH 

NEW 

1B49H 

CLEAR 

1E7AH 

NEXT 

22B6H 

CLOAD 

2 Cl FH 

NOT 

25C4H 

CLS 

01C9H 

ON 

1F6CH 

CONT 

1DE4H 

OUT 

2AFBH 

COS 

1541H 

PEEK 

2CAAH 

CSAVE 

2BF5H 

POINT 

0132H 

CSNC 

0AB1H 

POKE 

2CB1H 

DATA 

1F05H 

POS 

27F5H 

DEFDBL 

1E09H 

PRINT 

206FH 

DEFINT 

1E03H 

RANDOM 

01D3H 

DEFSNG 

1E06H 

READ 

21EFH 

DEFSTR 

1E00H 

REM 

TF07H 

DELETE 

2BC6H 

RESET 

0138H 

DIM 

2608H 

RESTORE 

1D91H 

EDIT 

2E60H 

RESUME 

1FAFH 

ELSE 

1F07H 

RETURN 

1EDEH 

END 

1DAEH 

RIGHTS 

2A91H 

ERL 

24DDH 

RND 

14C9H 

ERR 

24CFH 

RUN 

1EA3H 

ERROR 

1FF4H 

SET 

0135H 

EXP 

1439H 

SGN 

098AH 

FIX 

0B26H 

SIN 

1547H 

FOR 

1CA1H 

SQR 

13E7H 

FRE 

27D4H 

STOP 

1DA9H 

GOSUB 

1EB1H 

STRS 

2836H 

GOTO 

1EC2H 

STRINGS 

2A2FH 

IF 

2039H 

• SYSTEM 

02B2H 

INKEYS 

019DH 

TAN 

15A8H 

1NP 

2AEFH 

TROFF 

1DF8H 

INPUT 

219AH 

TRON 

1DF7H 

I NT 

0B37H 

USR 

27FEH 

LEFTS 

2A61H 

VAL 

2AC5H 

LEN 

2A03H 

VARPTR 

24EBH 

LET 

1F21II 





Table 1.3 — Disk Basic Entry Points 


CLOSE 

4185H 

CMD 

4173H 

CVD 

415EH 

CVI 

4152H 

CVS 

4158H 

DEF 

415BH 

EOF 

4161H 

FIELD 

417 Cl 1 

FN 

4155H 

GET 

417FH 

INSTR 

419DH 

KILL 

4191H 

LINE 

41A3H 

LOAD 

4188H 


LOC 

4164H 

LOF 

4167H 

LSET 

4197H 

MERGE 

418BH 

MKD$ 

4170H 

MKI$ 

416 AH 

MKS$ 

416DH 

NAME 

418EH 

OPEN 

4179H 

PUT 

4182H 

RSET 

419AH 

SAVE 

41A0H 

TIMES 

4176H 

& 

4194H 
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CHAPTER 2 

Registers, Buffers, and Varable Passage 


2.1. Variable Buffers and Holding Registers 

Nearly all of the Level II ROM routines to be detailed in Chapters 3, 4, and 5 require one or two input 
variables and return the value of an output variable. These routines expect to receive their inputs in certain 
common locations and/or registers and also deliver their outputs in common locations and/or registers. The 
following paragraphs describe these common modes of input—output variable passage. (The pertinent part of 
this information will be concisely repeated for each routine in Chapters 3, 4, and 5.) 

Integer variables are passed through the HL register pair, the DE register pair, and the memory locations 
4121H—4122H. Specifically, if a routine requires a single integer input, that input is passed through HL, or, 
for certain routines, through locations 4121H — 4122H. If a routine requires two integer inputs, these are 
passed through the HL and DE register pairs. In all cases, an integer output is stored in memory locations 
4121H—4122H and also (except for one routine in Section 3.4) in the HL register pair. 

Single precision variables are passed through memory locations 4121H—4124H and (in the case of a two- 
input routine) through the four registers BCDE. Specifically, if a routine requires one single precision input, 
that input is passed through memory locations 4121H—4124H, while two single precision inputs are passed 
using this memory area for one and registers BCDE for the other. (Register B contains the exponent, C the 
most significant byte of the mantissa, and E the least significant byte of the mantissa.) In all cases a single 
precision output will be stored in memory locations 4121H—4124H. 

Double precision variables are passed through (1) memory locations 411DH—4124H and (2) memory 
locations 4127H—412EH. Locations 411DH—4124H are used for a single (or first) input and for any output. 
Locations 4127H—412EH hold the second of two inputs. 

2.2. Subroutines to Move Variables 

Use of the ROM routines of Chapters 3, 4, and 5 requires the movement of variables between storage and 
the number buffer areas mapped out in the previous section, as well as between storage and the BCDE 
registers. There are several ROM subroutines that may be used to effect these movements for single precision 
variables. 

(a) To move a single precision variable from storage to the buffer area 4121H—4124H, load the HL register 

pair with the starting memory address of the variable (the address of the least significant byte) and 
CALL 09B1H. To move a single precision variable from the buffer area 412111—4124H to memory, 
starting at the address contained in the HL register pair,-CALL 09CBH. 

(b) To transfer a single precision variable 1mm registers 1JCDL to the buffer area 412111—4124H, CALL 

09B4H. To transfer a single precision variable from the buffer area 4121H—4124H to the registers 
BCDE, CALL 09BFH. 

(c) To transfer a single precision variable from storage to the registers BCDE, load the HL register pair with 

the starting memory address of the variable and CALL 09C2H. 


9 — 



(d) To move a single precision variable from the buffer area 4121H—4124H to the stack, CALL 0"A4H. In 
retrieving this variable from the stack, execute a POP BC followed by a POP DE; the variable bytes 
will then be in normal order in the BCDE registers. 
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CHAPTER 3 

Conversion Routines 


3.1. Single Precision to Integer 

The Level II ROM has three subroutines that convert single precision variables to integer variables. CINT 
always converts to an integer (using the greatest integer function) except when the input variable has absolute 
value greater than 32767, in which case an OV error occurs, returning control to the Level II monitor. INT 
will convert to an integer when possible (also using the greatest integer function), but will leave the result in 
single precision format (adjusted to a whole number) whenever the absolute value of the result exceeds 32767. 
Finally, FIX behaves like INT except that the whole number result is obtained by truncation. That is, FIX( — 
3.2) = —3, while INT(—3.2) = —4. Here are the details of using these routines: 

(a) CINT Follow these steps: 

(1) Store the input variable (in single precision format) in memory locations 4121H—4124H. 

(3) CALL 0A8AH. 

The integer result will be in 4121H—4122H and in the HL register pair. Overflow results in an OV error. 

(b) INT Follow these steps: 

(1) Store the input variable (in single precision format) in memory locations 4121H—4124H. 

(2) Store a 4 in 40AFH. 

(3) CALL 0B3DH. 

The result (in integer format) will be in 4121H—412211 and in the HL register pair if the absolute value of the 
input variable does not exceed 32767. Otherwise, the result will be in 4121H—4124H in single precision 
format, but adjusted to a whole number. Location 40AF will contain a 2 if the result is in integer format, or a 4 
if the result is in single precision format. 

(c) FIX Follow these steps: 

(1) Store the input variable, which may be either single or double precision, in 4121H—4124H (if single 

precision), or in 411DH—4124H (if double precision). 

(2) Store the variable type (4 for single precision, or 8 for double precision) in location 40AFH. 

(3) CALL 0B26H. 

If tKe result can be stored in integer format, it will be in 4121H—4122H and in HL. Otherwise, it will be in 
412IH—4124H (if input was single precision) or in 411DH— 4I24H (if input was double precision). Location 
40AFH will contain a 2, 4, or 8 for integer, single precision, or double precision output, respectively. 


3.2. Integer to Single Precision 

The following steps activate a routine in ROM that converts an integer to single precision format: 

(1) Store the input integer in 4121H—4122H. 

(2) CALL OACCH. 

The result (m single precision format) is in 4121H—4124H. 
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3.3. Number to Numeric String 

(n) To convert an integer, single precision, or double precision variable to its corresponding character string, 
follow these steps: 

(1) Store the variable in 412IH—4122H (if an integer), or in 4121H—4124H (single precision), or in 

411DH—4124H (double precision). 

(2) Store the variable type (2, 4, or 8, respectively) in location 40AFH. 

(3) CALL OFBDH. 

Upon return the character string is stored in locations 4130H and following, with a zero byte at the end. The 

HL register pair contains 4130H. Thus, the setup for video display of the character string-using the 

subroutine that will be described in Section 8.2 (b)-is complete. 

(b) Besides the two's complement integer format, there is a special 16—bit positive integer format that is used 
by the TRS—80 for line numbers and memory addresses. In this format no negative numbers may be rep¬ 
resented, but positive integers up to 65535 are allowed. 

EXAMPLE: In positive integer format, C5A3II represents 50545 (decimal). The same hexadecimal number 
in standard (two's complement) integer format would represent —14941 (decimal). 

To convert a number in 16—bit positive integer format to its corresponding character string, first load the 
number into the HL register pair, and then execute the following instructions: 

CALL 0A9AH 

XOR A 

CALL 1034H 

OR (HL) 

CALL 0FP9II 

Upon return from the subroutine at 010911, the character string will be in memory locations 413011 — 
4135H, right justified, with a zero byte in 4136H. On the left, the string is filled with spaces up to the leading 
digit. The HL register pair contains the address of the last space (the one just before the leading digit). Thus, if 
the subroutine of Section 8.2 (b) is used immediately to display the character string, it will appear with one 
leading space. (To suppress the leading space, simply INC HL before calling the subroutine of Section 8.2 (b).) 


3.4. Numeric String to Number 

(a) To convert a numeric string to a number in integer, single precision, or double precision format, follow 
these steps: 

(1) Have the characters assembled in consecutive memory locations, with either a comma or a zero byte at 

the end. 

(2) Load HL with the address of the first character. 

(3) CALL 0E6CH. 

The routine at 0E6CH converts to an integer if possible, with the result in 4121H—4122H and a 2 (for integer 
variable) in 40AFH. Otherwise, it converts to a single precision variable (with the output in 4121hf—4124H 
and a 4 in 40AFH), or to a double precision variable (with the output in 411DH—4124H and an 8 in 40AFH). 
(The double precision option is exercised il the input string has more than 7 digits.) 
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If it is desired that the input he converted to double precision format regardless of the number of digits 
entered, follow the above steps (1) and (2), but (step (3)) CALL 0E65H instead. The output will be in 
411DH—4124H, with an 8 in 40AFH. 

'The above method may be used to convert decimal constants needed by your assembly language program to 
machine format. Suppose, for example, that you require a single precision value for pi. Somewhere in your 
assembly language program you could write the following lines of code: 

P1STR DEFM '3.141593' 

DEFB 0 

(The DEFM and DEFB are assembler pseudo—ops for defining the contents of memory locations.) Then, 
when pi is needed, execute these instructions: 

LD HL.P1STR 

CALL 0E6CH 

Upon return, the value of pi in single precision format will be in 4121H—4124H. 

If several different constant conversions are required, a subroutine (named LOAD below) could be written 
to effect the equivalent of an "immediate load" each time a constant is needed. Here is a coding for such a 
subroutine: 


LOAD POP HL 

CALL 0E6CH 

INC HL 

PUSH HL 

RET 


When a value is required — say pi — execute the following: 

CALL LOAD 

DEFM '3.141593 ' 

(Note the comma terminating the string. Either that or a zero byte will do.) After execution of the above code 
the correctly converted value of pi will be in the buffer area 4121H—4124H. 

Of course, the subroutine at OE65H (to convert to double precision format) may be used instead of the one 
at 0E6CH in either of the above conversion procedures. 

(b) It is also possible to convert a character string representing an integer between 0 and 65535, inclusive, to 
16—bit positive integer format (discussed in the previous section). To do this, have the characters stored in 
consecutive locations in memory with a zero byte at the end. (The terminating zero byte is essential for this 
conversion routine.) Load the HL register pair with the address of the first character and CALL 1E5AH. The 
converted integer will be in the DE register pair upon return. (If the converted value of the string would 
exceed 65535, an SN error will occur, with control passing to the Level II monitor.) 
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CHAPTER 4 

Arithmetic Operations 


4.1. Addition 

There are three addition routines in the Level II ROM: one for integer operands, one for single precision 
operands, and one for double precision operands. 

(a) To add two integers, follow these steps: 

(1) Store one input in the DE register pair and the other in the III. register pair. 

(2) CALL 0BD2H. 

The result is in 4121H— 4122H and in HL, with a 2 in 40AFH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 4121H — 
4124H, with a 4 in 40AFH. (Overflow causes no error.) 

TIME: Integer addition requires approximately 130 microseconds. 

(b) To add two single precision numbers, follow these steps: 

(1) Store one input in the BCDE registers — exponent in B, least significant byte in E. Store the other input 

in 4121H—4124H. 

(2) CALL 0716H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 630 microseconds. 

(c) To add two double precision numbers, follow these steps: 

(1) Store the operands in 411DH—4124H and in 4127H—412EH. 

(2) CALL 0C771I. 

The result (in double precision format) is in 411DH—4124H. 

TIME: Approximately 1.3 milliseconds. 


4.2. Subtraction 

Again, there are three subtraction routines. 

(a) To subtract two integers, follow these steps: 

(1) Store the minuend in the DE register pair, and store the subtrahend (number to be subtracted) in the HL 

register pair. EXAMPLE: To calculate 26 — 17, store 26 in DE and 17 in HL. 

(2) CALL 0BC7H. 

The result is in 4121H—4122H and in HL, with a 2 in 40AFH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 4121H— 
4124H, with a 4 in 40AFH. (Overflow causes no error.) 

TIME: Approximately 210 microseconds. 
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(b) To subtract two single precision numbers, proceed as follows: 

(1) Store the minuend in the BCDE registers and store the subtrahend in 4121H—4124H. 

(2) CALL 0713H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 670 microseconds. 

(c) To subtract two double precision numbers, proceed as follows: 

(1) Store the minuend in 411DH—4124H and the subtrahend in 4127H—412EH. 

(2) CALL 0C70H. 

The result (in double precision format) is in 41IDM—4124H. 

TIME: Approximately 1.3 milliseconds. 


4.3. Multiplication 

There are also three multiplication routines. 

(a) To multiply two integers, follow these steps: 

(1) Store one input in DE, the other in HL. 

(2) CALL 0BF2H. 

The result is in 4121H—4122H and in HL, with a 2 in 40AFH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 4121H— 
4124H, with a 4 in 40AFH. (Overflow causes no error.) 

TIME: Approximately 900 microseconds. 

(b) To multiply two single precision numbers, proceed as follows: 

(1) Store one operand in the BCDE registers, the other in 4121H—4124H. 

(2) CALL 0847H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 2.2 milliseconds. 

(c) To multiply two double precision numbers: 

(T) Store one operand in 411DH—4124H, and store the other in 4127H—412EH. 

(2) CALL 0DA1H. 

The result (in double precision format) is in 411DH—4124H. 

TIME: Approximately 22 milliseconds. 


4.4. Division 

(a) To divide two integers: 

(1) Store the dividend in the DE register pair, and store the divisor in HL. EXAMPLE: To calculate 26/7, store 

26 in DE and 7 in HL. 

(2) CALL 2490H. 

The result is stored in single precision format (since it is not likely to be an integer) in 4121H—4124H. 
TIME: Approximately 5.1 milliseconds. 
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(b) To divide two single precision numbers: 

(1) Store the dividend in registers BCDE, and the divisor in 4121H—4124H. 

(2) CALL 08A2H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 4.8 milliseconds. 

(c) To divide two double precision numbers: 

(1) Store the dividend in 411DH—4124H, and the divisor in 
4127H—412EH. 

(2) CALL 0DE5H. 

The result (in double precision format) is in 411DH—4124H. 

TIME: Approximately 42 milliseconds. 

NOTE: All the division routines are subject to OV or 10 errors, which return control to the Level II monitor. 


4.5. Exponentiation 

To raise a single precision number (the base) to a single precision power (the exponent), follow these steps: 

(1) Store the base (single precision) in registers BCDE, and store the exponent (also single precision) in 

4121H—4124H. 

(2) CALL 13F7H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 50 milliseconds. 

NOTE: Fatal errors, returning control to the Level II monitor, can occur in the following ways: 

(a) If the base is negative, and the exponent is not a whole number. 

(b) If the absolute value of the result is as large as 2 to the power of 127. 

(c) If the base is zero, and the exponent is negative. 


4.6. Comparison 

Comparison is the operation of determining which of two numbers is the larger. Comparison can obviously 
be effected by a subtraction followed by testing the sign of the result. However, the routines described below 
are faster than the corresponding subtraction routines. In each of these routines, the result of the comparison 
is specified in exactly the same way by the following states of the Z—80 flags (which should be tested 
immediately after return from the routine): 


If the numbers are equal, the Z (zero) flag will be set. If they are not equal, the Z 
flag will be turned off. If the first input number is the smaller, the 5 (sign) and C 
(carry) flags will also be turned off. If the second input number is the smaller, 
the S and C flags will both be set. (The phrases "first input" and "second input" 
are used consistently in this paragraph and the following descriptions.) 
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(a) To compare two integers: 

(1) Store the first input in DE, the second in HL. 

(2) CALL 0A39H. 

Interpret the result as explained in the preceding paragraph. 

(b) To compare two single precision numbers: 

(1) Store the first input in registers BCDE, the second input in 4121H—4124H. 

(2) CALL OAOCH. 

Interpret the result as explained above. 

(c) To compare two double precision numbers: 

(1) Store the first input in 411DH—4124H, and store the second input in 4127H—412EH. 

(2) CALL 0A78H. 

Interpret the result as explained above. 

(d) The Level II ROM has a special, very fast routine for comparing two integers in 16—bit positive integer 
format (which is described in Section 3.3 (b).) To use this special routine, proceed as follows: 

(1) Store the first input in DE, the second in HL. 

(2) RST 18H. The RST (restart) is a special one—byte subroutine call. 

Interpret the result as explained in the paragraph preceding (a) above. 
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CHAPTER 5 

Mathematical Functions 


Each of the functions presented in this chapter requires one input variable and returns the value of one 
output variable. The first seven of these functions require their inputs in single precision format and return 
single precision outputs. 

5.1. SQR 

To find the square root of a nonnegative single precision number: 

(1) Store the number in 4121H—4124M. 

(2) CALL 13E7H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 48 milliseconds. 

NOTE: A fatal error (returning control to the Level II monitor) occurs if the input number is negative. 


5.2. EXP 

To find EXP(X), where X is a single precision variable: 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 1439H. 

The result (in single precisin format) is in 4121H—4124H. 

TIME: Approximately 28 milliseconds. 

NOTE: A fatal error occurs if the result is as large as 2 to the power of 127. 


5.3. LOG 

To find LOG(X), where X is a positive single precision variable: 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 0809H. 

The result (in single precision format) is in 412111—412411. 

TIME: Approximately 19 milliseconds. 

NOTE: A fatal error occurs if the value of the input variable is zero.or negative. 


5.4. SIN 

To find SIN(X), where X is a single precision variable: 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 1547H. 

The result (in single precision format) is in 4121H—4124H. 
TIME: Approximately 25 milliseconds. 

NOTE: The argument (X) must be in radians. 
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5.5. COS 


To find COS(X), where X is a single precision variable (in radians): 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 1541H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 25 milliseconds. 


5.6. TAN 

To find TAN(X), where X is a single precision variable (in radians): 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 15A8H. 

The result (in single precision format) is in 4121H—4124H. 

TIME: Approximately 54 milliseconds. 

NOTE: A fatal error occurs if the result is as large as 2 to the power of 127, which will be the case if the value 
of X is sufficiently close to any odd multiple of pi/2 radians. 


5.7. ATN 

To find ATN(X), where X is a single precision variable: 

(1) Store the value of X in 4121H—4124H. 

(2) CALL 15BDH. 

The result (in single precision format, in radians) is in 4121H—4124H. 
TIME: Approximately 27 milliseconds. 


5.8. SGN 

The signum function returns the value —1, 0, or +1, depending upon whether the input variable is negative, 
zero, or positive, respectively. The input can be an integer, single precision, or double precision number. To 
find SGN(X), proceed as follows: 

(1) Store the value of X in 4121H—4122H (integer), in 4121H—4124H (single precision), or in 411DH— 

4124H (double precision). 

(2) Store the variable type (2, 4, or 8, respecitvely) in 40AFH. 

(3) CALL 098AH. 

The result (in integer format) is in 4121H—4122H and in the HL register pair. 


5.9. ABS 

The input variable may be integer, single precision, or double precision. The output is in the same format as 
the input. To find ABS(X), proceed as follows: 

(1) Store the value of X in 4121H—4122H (integer), in 4121H—4124H (single precision), or in 411DH— 
4124H (double precision). 


— 19 — 



(2) Store the variable type (2, 4, or 8, respectively) in 40AFH. 

(3) CALL 0977H. 

The result (in the same format as the input variable) is in the same locations in which the input variable was 
stored. If the input was an integer, the result is also in the HL register pair. 


5.10. Random Number Generation 

(a) The random number generator keeps its 24 —bit seed number in memory locations 40AAH—40ACH. You 
may store any collection of bits in these locations to provide a (repeatable) starting point for random number 
generation in your programs. The RANDOM function in BASIC causes the contents of the R (memory 
refresh) register to be stored in location 40ABH. To accomplish this in assembly language programs, simply 
CALL 01D3H. 

(b) The RND(O) function in BASIC returns a single precision random number between 0 and 1, exclusive. To 
do the same thing in assembly language, CALL 14F0H. No input variable is necessary. The result (in single 
precision format) is in 4121H—4124H. 

TIME: Approximately 2.4 milliseconds. 

(c) The RND(J) function (with J a nonzero integer) is a BASIC function that returns a random integer between 
1 and J, inclusive. To do the same thing in assembly language, proceed as follows: 

(1) Load the value of J into the HL register pair. 

(2) CALL 14CCH. 

(3) CALL 0A7FH. 

The result (in integer format) is in 4121H—4122H and in HL. 

TIME: Approximately 5.7 milliseconds. 

NOTES: The input variable J must have a value between 1 and 32767, inclusive, or an FC error will occur, 
returning control to the Level II monitor. The CALL in step (3) above is to convert the single precision 
number produced by the routine at 14CCH to an integer. 
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CHAPTER 6 

Keyboard Input 


6.1. Single Character Input 

To input a single character from the keyboard, without posting it on the video display (essentially the 
INKEYS function), execute a CALL 035BH. On return from this routine, the character is in the A register. If 
the A register contains zero, no character was entered. 

DISK SYSTEM CAUTION: The subroutine at 035BH has an exit (via RST 28H and RAM address 400CH) 
to DISK BASIC. This exit is taken only if the keyboard entry was made with the BREAK key. To protect 
against this contingency, either be certain that DISK BASIC is in place when you use this routine, or have 
your assembly language program fill location 400CH with a RET (C9H) before calling this routine. 

A somewhat more primitive method for single character input, which is sometimes useful, is to examine 
the keyboard memory directly. The keyboard memory is not actually memory at all, but an area in which 
certain address lines are connected to the data lines by switch closures. It is possible to tell which keys are 
depressed by examining these "memory" addresses. In this manner it is possible to determine whether 
combinations of keys are depressed, and whether or not a key has been released. 

The following chart represents the keyboard memory. The horizontal rows are the address locations; the 
vertical columns are the data values. If the "A" key is depressed, for example, memory location 3801H will 
appear to have a value of 2; if both "A" and "B" are depressed, it will have the value 6. The locations with 
"XXX" are unused, and the location marked "PCL" is the location of the Electric Pencil control key. 
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6.2. Numeric Input 

The function of the assembly language program segment given below is to print "?" on the video screen at 
the current cursor position, to input a string of (supposedly) numeric characters from the keyboard — echoing 
each character to the screen — and to convert this string to a number in integer, single precision, or double 
precision format, as appropriate. Here is the coding: 

CALL 1BB3H 

INC HL 

CALL 0E6CH 

The output is in 4121H—4122H if it is an integer, in 4121H—4124H if it is single precision, or in 
411DH—4124H if it is double precision. The variable type (2, 4, or 8, respectively) is in 40AFH. 

NOTE 1: No checking of the input string is performed. Whatever is typed in will be converted to some sort of 
number. 

NOTE 2: If integer output is desired regardless of what is typed in, the above code may be followed by: 
CALL 0A7FH 

If this is done, a fatal error occurs if a number whose absolute value is larger than 32767 is entered from the 
keyboard. 

DISK SYSTEM CAUTION: The subroutine at 1BB3H has three exits to DISK BASIC, with transfer points 
at 400CH, 41AFH, and 41C1H. To use the routine safely, either be sure that DISK BASIC is in place, or have 
your assembly language program fill locations 400CH, 41AFH, and 41C1H with RET's (C9H) before calling 
this routine. In addition, this subroutine uses the keyboard buffer area whose starting address is stored in 
40A7H—40A8H. DISK BASIC maintains a usable keyboard buffer between its own program region and the 
beginning of the BASIC text area. However, if DISK BASIC is absent, the locations 40A7H—40A8H may 
contain an unusable address. It follows that, if DISK BASIC cannot be guaranteed, your assembly language 
program should — before using the subroutine at 1BB3H — assign a keyboard buffer area (either within its 
own memory limits or in high RAM) by storing a starting address for this buffer in 40A7H—40A8H. 


6.3. Consistency Checked Numeric Input 

(a) The function of the routine to be given below is to print a query (followed by a "?") on the video screen at 
the current cursor position, to input a string of (supposedly) numeric characters from the keyboard — echoing 
each character to the screen — and to convert this string to a number in the specified format. If the string is 
inconsistent (containing a nonnumeric character other than a single decimal point, for example), the routine 
will print "? REDO" on the screen, and will then repeat the query and accept a new input string. (This cycle 
will be repeated until the input string is consistent.) 

SETUP: The query (but not the "?") and a variable name have to be set up somewhere in your assembly 
language program. Let's suppose that we want to input a number in single precision format, and that we shall 
call it AVI. (The "!" may not be necessary unless a declaration statement in your BASIC program defines the 
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variable type of variables whose names begin with A as other than single precision.) Assume also that the 
query is to be "AVERAGE?". Let us set this up in memory locations starting at the (symbolic) address 
QUERY: 


QUERY DEFM ' "AVERAGE";AV! ' 

DEFB 0 


(The quotes around the query, the semicolon after the query, and the zero byte following the ASCII bytes for 
the query and variable name are all essential for the proper operation of the routine below.) 

The following assembly language routine will accomplish the function described above, with the label 
QUERY corresponding to the label in the setup just given: 


RETRY 


LD 

HL,QUERY 

i.n 

A,(HL) 

CALL 

21C9H 

LD 

A,(Hl.) 

OR 

A 

JR 

NZ,RETRY 


The result (in the format specified implicitly by the variable name) will be in 4121H—4122H if an integer, 
4121H—4124H if single precision, or 41IDI1—412411 if double precision. 

NOTE 1: If your assembly language program is entered via a SYSTEM command (rather than through a USR 
call), it will need to initialize the stack pointer at some high core location. Otherwise, an OM error may occur 
in the above routine. (See Section 10.1.) 

NOTE 2: The above routine sets up the variable name, type, and value in the BASIC variable storage area, or 
replaces a Value already there. If a comma is inadvertently entered from the keyboard, "EXTRA IGNORED" 
will appear on the screen, and the value stored in 4121H— 4122H, 4121H—4124H, or 411DH—4124H will be 
destroyed; the correctly converted value (for the characters preceding the comma) will still appear in variable 
storage, however, and may be retrieved from there by use of the VARPTR routine described in Section 10.2. 
(The starting address of the BASIC variable storage area is contained in locations 40F9H—40FAH. Be sure 
that your assembly language program does not overlap this area if it uses the above routine.) 

NOTE 3: This routine is still subject to an OV error in at least two cases: (1) The specified format is integer, 
and a number whose absolute value is larger than 32767 is entered, or, (2) The specified format is single or 
double-precision, and the typist enters a number in E format with an exponent that is too large in absolute 
value. 

DISK SYSTEM CAUTION: Since the subroutine at 21C9I1 calls the subroutine at 1BB3H, the DISK 
SYSTEM CAUTION of Section 6.2 applies. (If DISK BASIC cannot be guaranteed, put RET's in 400CH, 
41AFH, and 41C1H, and assign a keyboard buffer area by storing its starting address in 40A7H—40A8H.) In 
addition, the subroutine at 21C9H has five more RAM transfer points to DISK BASIC, which should also be 
filled with RET's if DISK BASIC may not be in place when the subroutine is used. These other transfer points 
are: 41ACH, 41BEH, 41D0H, 41DCH, and 41DFH. 
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(b) In connection with the checking of numeric strings, there is another routine in the Level II ROM that is 
worth mentioning. This routine is activated by 

RST 10H 

and performs the following function: The character at the memory location one greater than that contained in 
the HL register pair is examined. If it is a space, the next character is examined; this loop is repeated until a 
character other than a space is found. The first character other than a space is then checked. If it is a digit 
(0—9), the C (carry) flag is set; otherwise, the C flag is turned off. Then, the routine returns control to the 
calling program with HL pointing to the checked character and the character itself in the A register. 


6.4. String Input 

(a) To display "?" on the video screen at the current cursor position, and then to input a string of up to 240 
characters, execute 


CALL 1BB3H 

The input string will be in consecutive memory locations starting at the address contained in 40A7H — 
40A8H, with a zero byte at the end. The HL register pair will contain an address one less than the starting 
address of the stored input. (See the DISK SYSTEM CAUTION of Section 6.2 regarding the use of this 
subroutine in disk systems.) 

(b) Here is a method of restricting the number of keyboard characters that will be accepted for input. If no 
more than n characters are to be allowed, use this assembly language program segment: 

LD HL,(40A7H) 

LD B,n 

CALL 05D9H 

Up to n characters will be accepted, after which the keyboard will simply be ignored until the ENTER (or LEFT 
ARROW, or BREAK, or CLEAR) key is pressed. These characters will be stored in consecutive memory cells 
starting at the address contained in 40A7H—40A8H (the keyboard buffer area), with a ODH (carriage return) 
byte at the end. Upon completion, the HL register pair will contain the address of the first character of the 
stored input, and the B register will contain the number of characters entered. 

NOTE: No "?" is displayed as a result of the execution of the above program. If the "?" display is desired to 
prompt the typing of the input, precede the above program segment with: 


LD 

A,3FH 

CALL 

033AH 

LD 

A,20H 

CALL 

033AH 


— 24 — 



DISK SYSTEM CAUTION: If DISK BASIC may not be present when this routine is used, the keyboard 
buffer area should be assigned by storing an appropriate starting address in 40A7H—40A8H before executing 
the above code. Also, the subroutine at 05D9H has an exit to DISK BASIC with transfer point at 400CH, 
which should therefore be filled with a RET (C9H) if DISK BASIC may be missing when the subroutine is 
called. 


6.5. Intercepting the Keyboard Driver 

The ROM keyboard driver is a subroutine that scans the keyboard for input and decodes each character as it 
is entered. The entry point address of the ROM keyboard driver routine is 03E3H, and this is the address 
normally stored in the keyboard DCB at locations 4016H—4017H. By replacing the address in 4016H — 
4017H with the entry point address of your own assembly language program, you can either (1) substitute 
your own keyboard driver for that of the ROM, or (2) put your own keyboard pre-processing routine in 
front of the ROM's keyboard driver. (Various keyboard debounce programs operate on this second principle.) 
Thus, you can modify the interpretation of keyboard input to suit your particular requirements. A program 
that substitutes for the entire keyboard driver should end with a RET, while a program for pre-processing 
may end with a JP 03E3H. 
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CHAPTER 7 

Cassette Input—Output 


7.1. Tape On—Off, Leader, and Sync 

(a) To turn on the cassette, execute the following instructions: 

LD A,0 

CALL 0212H 

(b) To write leader and sync byte: 

CALL 0287H 

(c) To search for leader and sync byte: 

CALL 2%H 

(d) To turn the cassette off: 

CALL 01F8H 


7.2. Single Character Input—Output 

(a) To write a character onto cassette tape (after the cassette has been turned on and leader and sync have been 
recorded), load the character into the A register and CALL 0264H. If more than one character is to be written, 
the CALL 0264H must be executed with sufficient frequency to sustain the 500 baud recording rate. The 
routine provides automatic timing. 

(b) To read a character from cassette (after the cassette has been turned on and leader and sync have been 
found), CALL 0235H. The input character will be in the A register. Again, the routine at 0235H must be 
called frequently enough to sustain the 500 baud rate if more than one character is to be read. 


7.3. CLOAD and CSAVE 

(a) Before CLOAD is called, the HL register pair should be loaded with the address of a zero byte, or the 
address of the first character of a string containing the program name, in quotes, followed by a zero byte. A 
B2H byte (a ROM code for "?") may (optionally) appear as the first character of this string if it is the tape 
verification function that is desired. The entry point of CLOAD is 2C1FH. CLOAD is not a closed subroutine. 
After 


CALL 20 FH 
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control will not return to the calling program, but will pass instead to the Level II monitor. Since control is not 
returned to the calling program, a )P 20 F! I works as well as CALL 20 FH. 

NOTE: If CLOAD is called (or jumped to) from an assembly language program that is itself entered via the 
SYSTEM command (rather than through a USR call), the stack pointer should first be initialized to a high 
RAM location. Otherwise, an OM error will occur, returning control to the Level II Monitor. (See Section 
10.1 for a fuller discussion of this point.) 

DISK SYSTEM NOTE: CLOAD probably has no usefulness in an assembly language program in a disk 
system. In any case, it should not be used in the absence of DISK BASIC, since it returns control to the Level 
II monitor, which has many exits to DISK BASIC. 

(b) CSAVE is a closed subroutine, as are all of the ROM routines that arc described in this book, with the sole 
exception of CLOAD. Before CSAVE is called, the HL register pair should be loaded with the address of the 
first character of a string containing the program name, in quotes, followed by a zero byte. The entry point of 
CSAVE is 2BF5H. 


EXAMPLE: Suppose that it is desired to record a program named "S". (Only the first character of the name is 
put onto tape.) First, the name (in quotes), followed by a zero byte, has to beset up somewhere. This can be done 
symbolically as follows: 


PRGNAM DEFM ' "S'* ' 

DEFB 0 


Then, execute these instructions: 


LD HL,PRGNAM 

CALL 2BF5H 


7.4. Tape Formats 

In this section four types of tapes are considered. These are: BASIC program rapes created with the CSAVE 
command, data tapes created by the BASIC statement "PRINT#—1”, source code output from the TRS—80 
Editor/Assembler, and standard machine language tapes loaded with the SYSTEM command. All of these tape 
formats begin in the same way. This is with a leader of 256 byte's of zeroes, followed by a sync byte of A5H. 
After this, the formats diverge. 
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(a) BASIC Format 


Leader and sync byte 
D3H D3H D3H 

XX 

;tape type identifier 
;ASC1I value of program name 

XX (LSB) 

XX (MSB) 

XX (LSB) 

XX (MSB) 

XX XX XX... 

00 

;two byte address of NEXT 
.•program line 
;line number of PRESENT 
;program line 

.-current line program text (compressed format) 

;zero 

(repeat above block un 

til end) 

00 00 

;double zeroes indicate end of program 

Though the BASIC tape format includes specific addresses, the CLOAD subroutine will load programs 
originally saved in a system with different addresses. For example, BASIC programs saved in Level II will load 
into DISK BASIC even though the addresses are completely different. The format of BASIC program text in 
memory is exactly the same as the tape format, with the exception that the leader, tape type identifier, and 
file name are not stored. 

(b) PRINT#-1 Format 


Leader and sync byte 


XX XX XX... 

2CH 

;ASCII string 
;comma (see below) 


(repeat above block for each value) 


ODH ;end byte 

The data block is repeated, with a maximum number of 255 characters for each leader and sync byte. The 
last value is not, however, followed by a comma. If only one value or string is output, no comma appears at 
all. Numeric values are saved as ASCII strings with a leading and trailing space (20H). Because several seconds 
of time are taken to write each leader, data storage on cassette is very slow. The INPUT#—1 statement, 
however, does not usually need such a long leader. A substantial reduction of tape storage time can be 
accomplished by writing a custom machine language subroutine to write tape data with a short leader. (See 
Appendix 3.) 
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(c) Editor/Assembler Source Code Format 


Leader and sync byte 

D3H ;tape type identifier 

XX XX XX XX XX XX ;6 letter file name, padded with spaces (2011) 


XX XX XX XX XX ;5 digit ASCII line number with bit 7 set 

20H ;space 

XX XX XX... dine text in ASCII 

ODH .carriage return 


(repeat above block for each line) 


1AH 


;end of file marker 


(d) SYSTEM Tape Format 
Leader and sync byte 

55H .tape type identifier 

XX XX XX XX XX XX ;6 letter file name, padded with spaces (20H) 


3CH ;block sync 

XX ;data length (0 represents 256) 

XX ;load address (LSB) 

XX ;load address (MSB) 

XX XX XX... ;data bytes 

XX checksum (sum of data and load address) 


(repeat above block for length of program) 


78H 

;block sync for end of file 

XX 

;execute address (LSB) 

XX 

,-execute address (MSB) 
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CHAPTER 8 

Video Output 


8.1. Numeric Output 

To convert a number to a string of digits, and to display the latter on the video screen starting at the current 
cursor position, proceed as follows: 

(1) Store the number in 4 121H—4122M (if it's an integer), or in 4121 If—4124H (if it's single precision), or 

in 411DH—4124H (if it's double precision). 

(2) Store the variable type (2, 4, or 8, respectively) in 40AFH. 

(3) CALL OFBDH. 

(4) CALL 28A7H. 

NOTE 1: The routine at OFBDH is the conversion routine described in Section 3.3 (a). The subroutine at 
28A7H is a general program for displaying a string of characters and updating the cursor position. The string 
to be displayed must be terminated by a zero byte, and the HL register pair must contain the address of the 
first character of the string before 28A7H is called. (The routine at OFBDH effects this setup automatically. 
See also Section 8.2 (b).) 

NOTE 2: Many of the ROM routines described in this book require a numeric input (or inputs). For most of 
these, the instructions given for calling them have not included the storage of the variable type flag in 40AFH. 
The reason is that, wherever possible, the variable type flag storage has been finessed by the choice of the 
subroutine entry point. In the routine of this section, that has not been possible, nor was it possible for the 
INT (Section 3.1 (b), the FIX (Section 3.1 (c)), the Number to Numeric String (Section 3.3 (a)), the SGN 
(Section 5.8), or the ABS (Section 5.9) routines. Storing a 2, 4, or 8 in 40AFH takes only 5 bytes of machine 
code, but there are subroutines in the Level II ROM that can reduce the required code to 3 bytes. CALL 
0A9DH will store a 2 in 40AFH. CALL OAEFH will store a 4 in 40AFH. And, finally, CALL OAECH will store 
an 8 in 40AFH; this last subroutine, however, destroys the contents of the BC register pair. 

DISK SYSTEM CAUTION: The subroutine at 28A7H has two exits to DISK BASIC, with RAM transfer 
points at 41 ClH and 41D0H. To use this routine safely, either be certain that DISK BASIC is in place, or have 
your assembly language program fill locations 41C1H and 41D0H with RET's (C9H), before calling the 
routine. 


8.2. String Output 

(a) To print a single character at the current cursor position, and to update the cursor position, follow these 
steps: 

(1) Load the ASCII value of the character into the A register. 

(2) CALL 033AH. 

(b) To display a string of characters starting at the current cursor position, and to update the cursor position, 
proceed as follows:. 

(1) Store the characters in consecutive memory locations, with a zero byte at the end. 

(2) Load the HL register pair with the address of the first character of the string. 

(3) CALL 28A7H. 
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EXAMPLE: Suppose that we have the following symbolic setup: 


T1TL DEFM 

DEFB 


Then, the instructions 


LD 

CALL 


'INSIDE LEVEL II' 
0 


HL,TITL 

28A7H 


will cause “INSIDE LEVEL II" to be displayed at the current cursor position and the cursor position to be 
updated. 

NOTE: If the subroutine at 28A7H is used by an assembly language program that is itself entered by a USR 
call, the return from the assembly language program may encounter the embarrassment of a TM error, with 
control passing to the Level II monitor. This occurs because the subroutine at 28A7H leaves a 3 in location 
40AFH, while the USR structure requires a 2 in 40AFH upon returning. The malady is cured by storing a 2 in 
40AFH before returning, or by jumping to 0A9AH instead of executing the simple RET. The problem would 
not occur in the first place if the assembly language program returns the value of an integer variable to the 
BASIC program, and it might not occur if some other ROM routine is called after the subroutine at 28A7H 
and before returning — if the other subroutine produces an integer output. 

DISK SYSTEM CAUTION: See the DISK SYSTEM CAUTION of Section 8.1 regarding the exits to DISK 
BASIC from the subroutine at 28A7H. 
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CHAPTER 9 

Video Display Control 


9.1. CLS 


To dear the screen, CALL 01C9H. The cursor is reset to the home position, which is 3C00H. 


9.2. Tabbing 

To locate the cursor at position n on the current display line, where n is an integer between 0 and 3FH, 
inclusive, proceed as follows: 

(1) Load the E register with the value of n. 

(2) Load the HL register pair with the address of a zero byte in memory. 

(3) CALL 213FH. 

NOTE 1: The cursor position cannot be moved backward by this procedure. If n is not greater than the current 
cursor position on the line, no change will occur. 

NOTE 2: To locate the cursor at a given position on the screen (the function of the PRINT@ command in 
BASIC), the simplest procedure is to modify the cursor position bytes, which are located at 4020H— 1021H. 
The address contained in these memory cells is that of the position in video memory (3C00H—3FFFH) at 
which the (abstract) cursor resides. This cursor position controls subsequent printing via the subroutine at 
28A7H, described in Section 8.2 (b). 

DISK SYSTEM CAUTION: The subroutine at 213FH has three exits to DISK BASIC, with RAM transfer 
points at 41BEH, 41C1H, and 41D3H. To use this routine safely, either be certain that DISK BASIC is in 
place, or have your assembly language program fill locations 41BEH, 41C1H, and 41D3H with RET's (C9H), 
before calling the routine. 


9.3. Scrolling 

To scroll (shift the entire display upward one line), CALL 0553H. 


9.4. Partial Clearing of Screen 

To clear the video screen from (including) position N — where N is an integer between 0 and 1023 (deci¬ 
mal), inclusive — to the end of the display, proceed as follows: 

(1) Load the HL register with the value 3C00H + N. 

(2) CALL 057CH. 
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9.5. Special Display Functions 


Each of the special display functions listed below can be accomplished by the following procedure: 

(1) Load the A register with the value given below for the special function. 

(2) CALL 033AH. 

Here are the functions and their integer codes: 


(a) Backspace and erase previous character-08H 

(b) Carriage return and line feed-ODH 

(c) Turn on cursor-OEH 

(d) Turn off cursor-OFH 

(c) Convert to 32 characters per line mode-17H 

(f) Backspace cursor-18H 

(g) Advance cursor one position-19H 

(h) Downward line feed-1AH 

(i) Upward line feed---1BH 

(j) Home (cursor to upper left corner)-1CH 

(k) Move cursor to beginning of current line-1DH 

(l) Erase from cursor position to end of line-1EH 

(m) Erase from cursor position to end of screen-1FH 
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CHAPTER 10 

Miscellaneous Routines and Information 


10.1. Stack Pointer 

When an assembly language routine is entered via a USR call, the Z—80 stack pointer contains a high RAM 
address, because the Level II monitor sets up the stack in high RAM for its own purposes. Using this same stack 
area for your assembly language programs is a sound practice, whether your programs are in high core (above 
the stack, as intended by the designers of the TRS—80 software) or in low core (below the BASIC program, as 
will be recommended in Part II of this book.) 

However, if an assembly language routine is entered via a SYSTEM command, the stack pointer will be 
initialized to4288H by the Level 11 monitor. The assembly language routine may then need to relocate the stack 
by loading the stack pointer with a high RAM address. This will be the case if the routine calls a ROM routine 
that checks for room in memory (CLOAD, or the routine described in Section 6.3 (a)), because the HL register 
pair is likely to contain an address higher than the stack — resulting in an OM error — unless the stack is moved 
to high core. 


10.2. VARPTR 

When used with a numeric variable as its argument, the VARPTR routine returns the address of the first byte 
of the value of that numeric variable. When used with a string variable as its argument, VARPTR returns the 
address of the first byte of a three—byte "dope" block that has the following structure: the first byte of *his 
block contains the number of characters in the string, and the next two bytes of the block contain the address of 
the first character of the string. (See pages 8/8 and 8/9 of the Level II Basic Reference Manual.) These 
functions make VARPTR one of the most useful routines in ROM, because it helps us to link our assembly 
language and BASIC programs smoothly. (See Part II, especially Chapter 13.) 

To use VARPTR, we need to have set up in memory the name of the variable that we wish to reference, 
followed by a zero byte. Suppose, for example, that we want the address of the first byte of the value of the 
variable Al%. We might then use the following symbolic setup: 

VARNAM DEFM 'Al%' 

DEFB 0 

To get our address, we execute these instructions: 

LD HL,VARNAM 

CALL 260DH 

Upon return, the DE register pair contains the desired address. If the variable has not yet been established by the 
BASIC program, the above procedure will set it up in BASIC variable storage (with a value of 0) and return the 
address of the first byte of its value. 
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If in the above example we change the setup to read 


VARNAM DEFM 'Al$' 

DEFB 0 


then the same machine language instructions given there will fetch (into the DE register pair) the address of the 
first byte of the three—byte "dope" block for the string variable Al$. 

The above examples involve a string variable and a simple numeric variable. How does one obtain the location 
of a numeric array variable? The easiest method to use is to secure the address of the first variable in the array 
and then to compute the address of that particular member of the array that is needed. The following facts must 
be kept in mind in order to carry out this procedure sucessfully. 

(1) The first member of an array is indexed by 0's. For example, if the array name is AR, then AR(0) is the 

first member if the array is one—dimensional, AR(0,0) is the first member if it is two-dimensional, 
etc. 

(2) The members of an array are stored in memory in order of increasing first index, then by increasing 

second index, then by increasing third index, etc. As an example, if the array AR is three- 
dimensional, with dimension numbers specified by DIM AR(2,1,1), then its 12 members are stored in 
memory in the following order (read across before descending): 


AR(0,0,0), 

AR(0,1,0), 

AR(0,0,1), 

AR(0,1,1), 


AR(1,0,0), 

AR(1,1,0), 

AR(1,0,1), 

AR(1,1,1), 


AR(2,0,0), 

AR(2,1,0), 

AR(2,0,1), 

AR(2,1,1) 


(3) The spacing between successive members of an array in memory is the number of bytes required to 

represent each number in the array — 2 for an integer array, 4 for a single precision array, or 8 for a 
double precision array. 

(4) If the array is more than one—dimensional, then the assembly language routine needs to know the 

dimension numbers of the array. For the example above (AR with dimension numbers 2,1,1), the 
assembly language routine needs to know the 2 and the first 1 (which will be 3 and 2, respectively, in 
the calculations) in order to compute the addresses of the variables in the array. 


The following example should clarify the above points. 

EXAMPLE: Suppose that AR is a single precision array dimensioned by the BASIC statement DIM AR(5,3,2). 
Suppose that we want the address of AR(2,2,1). First, the symbolic setup: 

ARNAM DEFM 'AR(0,0,0)' 

DEFB 0 

may be used to define the name of the first member of the array. Then, the instructions 


LD 

CALL 


HL,ARNAM 
260DH 



will fetch the address of AR(0,0,0) into the DE register pair. To this address must be added 4x(2+2x6+lx6x4). 
In this expression, the leftmost 4 is the number of bytes in the representation of a single precision variable, the 
2, 2,1 appearing inside the parentheses are the indices of the desired member of AR, the 6 (in both occurrences) 
is the range of the first index (0 to 5 covers 6 integral values), and the final 4 is the range of the second index. 


10.3. String Replacement 

After VARPTR has been used by an assembly language program to find a BASIC string variable, and after 
this string variable has been manipulated, there may arise the problem of replacing the variable in BASIC string 
variable storage. This problem seems particularly difficult if the modified string is longer than the original. In 
any case, the ROM routine described next may be used to effect the replacement. 

SETUP: The string should be held in a buffer area (preferably below the start of the BASIC text area as defined 
by the address in locations 40A4H—40A5H), with an uncommitted byte of memory in front of the string, and a 
zero byte at the end of the string. (The content of the uncommitted memory cell is immaterial.) Also, the name 
of the string needs to be set up somewhere with a zero byte at the end, as for example: 

VARNAM DEFM 'B$' 

DEFB 0 

Then, proceed as follows: 

(1) Load the HI. register pair with the address of the uncommitted byte just preceding the first character of the 

string. 

(2) Load the BC register pair with the address of the first character of the variable name (VARNAM in the 

above setup). 

(3) CALL 21E3H. 

NOTE: If the string is held in a buffer area that is below the start of the BASIC text area as defined b • the address 
in 40A4H—40A5H, then the string will be placed in BASIC string variable storage by the routine at 21E3H. 
However, if the address of the string in its buffer area is higher than the starting address of the BASIC text area, 
then the string will not be moved at all; instead, its three—byte "dope" block will be adjusted to point to the 
string in its buffer area. It follows that you should not use a buffer area above the BASIC text area for the 
purpose of assembling a BASIC string unless you are willing to have that buffer area committed (that is, 
unusable for later operations on other strings.) 

DISK SYSTEM CAUTION: The subroutine at 21E3H has three exits to DISK BASIC, with RAM transfer 
points at 41BEH, 41DCH, and 41DFH. Either fill these locations with RET's (C9H), or be certain that DISK 
BASIC is in place before using this subroutine. 


10.4. LET 

The BASIC command LET (for assignment of variable values) is implemented by a subroutine with entry 
point at 1F21H. It is possible to use this subroutine in assembly language programs; simply follow these steps: 

(1) Load HL with the address of the first character of an appropriately modified assignment statement string 

that is terminated by a zero byte. 

(2) CALL 1F21H. 
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Examples of assignment statements are: 

(a) Z = SQRfX'X + Y*Y) 

(b) AS = B$ + MID$( C$,2,3) 

(c) E(I,J) = F(I,1)*C(1,J) + F(I,2)'C.(2,J) 


By "appropriately modified assignment statement string" is meant a string consisting of the characters of an 
assignment statement in which the equals sign, each operator, and each function has been replaced by the 
one—byte code that the Level 11 ROM employs for that sign, operator, or function. Here is a complete list of 
these one—byte codes: 


+ 

CDH 

COS 

E1H 

OR 

D3H 

— 

CEH 

CSNG 

FOH 

PEEK 

E5H 

* 

CFH 

EXP 

EOH 

POINT 

C6H 

/ 

DOH 

FIX 

F2H 

POS 

DCH 

t 

D1H 

FRE 

DAH 

RIGHTS 

F9H 

= 

D5H 

INKEYS 

C9H 

RND 

DEH 

ABS 

D9H 

INP 

DBH 

SGN 

D7H 

AND 

D2H 

INT 

D8H 

SIN 

E2H 

ASC 

F6H 

LEFTS 

F8H 

SQR 

DDH 

ATN 

E4H 

LEN 

F3H 

STRS 

F4H 

CDBL 

F1H 

LOG 

DFH 

STRINGS 

C4H 

CHR$ 

F7H 

MEM 

C8H 

TAN 

E3H 

Cl NT 

EFH 

MIDS 

FAH 

VAL 

FSH 


The LET subroutine will fetch (from the BASIC storage area) the values of all the variables on the right side of 
the assignment statement, will perform the indicated calculations, and will return the result (to BASIC storage) 
as the value of the variable on the left side of the assignment statement. 

One significant use of the LET subroutine would be in a program that permits the entry of a function from the 
keyboard during execution, sets that function up as the right side of an assignment statement, and then calls the 
LET subroutine to evaluate the function. (Plotting and numerical integration programs are examples.) For this 
application it is helpful to have a subroutine that scans the assignment statement string, replacing the equality 
sign, each function, and each operator with its one—byte code as given in the table above. Such a routine exists 
in fhe ROM, with entry point at 1BC0H. The following code will modify an assignment statement string that 
has starting (symbolic) address ASSIGN (and that is terminated by a zero byte), will evaluate the right side of 
the assignment statement, and will store the result in BASIC variable storage as directed by the left side of the 
assignment statement: 


LD 

HL,ASSIGN 

CALL 

1BC0H 

INC 

HL 

CALL 

1F21H 


NOTE: The modified string will be assembled in the keyboard buffer area starting at the address that is 3 less 
than the address contained in 40A7H—40A8H. If DISK BASIC may not be present, your assembly language 
program should assign this buffer area by storing an appropriate address in 40A7H—40A8H before calling the 
subroutine at 1BC0H. 
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10.5. Output to Line Printer 

The entry point address of the line printer driver is 003BH. To output a character to the line printer, load the 
A register with the ASCII value of the character and CALL 003BH. 


10.6. POINT, SET, RESET 

These routines, whose functions are described on pages 8/1 and 8/2 of the Level II Basic Reference 
Manual, arc activated in similar manner by the following procedure: 

(1) Load HL with the return address. 

(2) PUSH HL 

(3) Load the HL register pair with the address of a right parenthesis character in memory. 

(4) Load the A register with an identifier: 0 for POINT, 1 for RESET, or 80H for SET. 

(5) PUSH AF 

(6) Load A with the value of the X coordinate (an integer between 0 and 7FH, inclusive). 

(7) PUSH AF 

(8) Load A with the value of the Y coordinate (an integer between 0 and 2FH, inclusive.) 

(9) JP0150H 

If the function is POINT, upon return the desired indicator (0 if (X,Y) is off, —1 if it is on) will be in 
4121H—4122H. 


10.7. RUN 

To RUN a BASIC program, starting with its first line, execute the following instructions: 

LD HL,1D1EH 

PUSH HL 

JP 1B5DH 

The ability to RUN a BASIC program from an assembly language program is valuable for linking the two 
programs, as will be shown in Part II. (See especially Chapter 14.) 


10.8. Re—entry to Level II Monitor 

The normal re-entry to the Level II Monitor is JP 1A19H. A jump to 0 will effect a complete restart 
(including the "MEMORY SIZE?" display in a diskless system). 
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PART II 


Linking Assembly Language and BASIC Programs 
CHAPTER 11 

Assemblers and Monitors 


Hand assembly of assembly language programs of more than a few dozen instructions is tedious, and the 
correcting of errors in such programs by hand reassembly is not to be recommended to your worst enemy. 
Obviously, to take full advantage of the information in this book you will need an assembly program. The 
TRS—80 Editor/Assembler (cassette version) is readily available, works well, and is easy to use. Recently a 
disk version of this assembler has been produced. Unfortunately, the cassette and disk versions differ some¬ 
what in their notational conventions. The assembly language examples and listings in this book conform to 
the conventions of the cassette version of the TRS—80 Editor/Assembler. 

Another sort of program that is nearly essential in constructing and debugging assembly language prog¬ 
rams is a machine language monitor. A number of monitors are currently available. The TRS—80 T—BUG 
monitor is rather primitive and has the serious flaw that it loads into low RAM, where it conflicts with the 
composite programs that are the subject of the remainder of this book. Other satisfactory monitors exist. 
Mumford Micro Systems offers a monitor named MicroMind that has been specially designed as a companion 
piece to this book. MicroMind incorporates the following features: 

(1) It will run in any Level II 16K (or larger) system, with or without a disk. 

(2) It comes with a relocation program that enables its relocation to any convenient place in RAM. 

(3) It allows you to examine and change memory, examine and change the registers, set and restore break 
points, transfer control to any point in memory (including ROM), and record and verify SYSTEM tapes. 

(4) Assembly language programs can be executed one instuction at a time, with two full register displays- 

one before and one after the execution of each instruction. Any number of instructions (up to 255) can be 
executed at high speed by a special RUN command. Also, subroutines may be executed in full with a single 
command. 

(5) Ease of use has been a principal consideration in the design of MicroMind. For example, addresses may be 
entered in either decimal or hexadecimal without any awkward postfixes. Also, the flags are displayed, and 
can be examined and changed, individually, rather than as hard—to—remember bits in a general flag register. 

(6) MicroMind occupies only 2288 bytes of memory. 


— 39 — 



CHAPTER 12 

Relocating a BASIC Program 


When one writes a composite BASIC anil assembly language program for the TRS—80, standard practice 
dictates that the BASIC program shall reside in low core, while the assembly language program shall occupy 
high core. There are two operational defects in this scheme: 

(1) Before the combined program can be loaded, the memory size must be set to accommodate the assembly 

language part. Otherwise, the BASIC program's string storage will overlap the assembly language 
area. 

(2) Loading the combined program involves two separate loading actions — a CLOAD and a SYSTEM load, 

if the programs are on tape. 

Defect (2) can be partially corrected in tape systems by loading the assembly language program first, then 
running it, whereupon it causes the BASIC program to be loaded by executing a CLOAD, as described in 
Section 7.3. The operator then has to perform only one loading action (a SYSTEM load), but he has to run 
twice — once from the SYSTEM state, and once from the READY (monitor) state, since CLOAD returns 
control to the monitor. For details of implementing this method, see the end of Chapter 14. 

An entirely different approach is possible. It is the purpose of the remainder of this book to show how to 
combine program sections so that the assembly language part resides in low core, the BASIC part is located 
immediately above this, and the two parts arc recorded on a single tape segment that can be loaded under the 
SYSTEM command and run from there (one load, one run). Besides eliminating the two defects mentioned 
above, this approach secures the superior features of the SYSTEM load (6—character titles and check sum 
testing) and also results in maximum compactness of the composite program in memory. 

A BASIC program is inherently relocatable. The reason that a CLOAD causes a BASIC program to be 
stored in memory starting at 42E9H (or considerably higher if you have an operating disk) is that locations 
40A4H—40A5H contain the address 42E9H (or higher, with a disk), and the monitor commences loading at 
the address contained in these locations. It follows that, if you were to change the address in 40A4H—40A5H 
to 7000H, say, your BASIC programs would load starting at 7000H. They would load there, but they might 
not run correctly unless you had also taken care to store a zero byte in 6FFFH (in general, the location just 
before the starting load address). 

Now you know how to load a BASIC program into any part of RAM. This technique could be employed to 
load two separate BASIC programs into adjacent memory blocks, which would allow you to combine them 
into one program, provided that the second program has line numbers all of which are higher than any of the 
line numbers in the first program. However, to do this successfully, you obviously have to be able to learn 
where theiirst program ends. After a CLOAD, locations 40F9H—4PFAH contain the address of the start of 
simple variable storage, which is just 3 bytes higher than the address of the last byte of the BASIC program. 
Thus, the following procedure permits combining two BASIC programs when the second has all higher line 
numbers than the first: 

(1) Load the first program via CLOAD. 

(2) PEEK at the address in 40F9H—40FAH, and store 2 less than this address in 40A4H—40A5H. 

(3) Load the second program via CLOAD. 

(4) Reset the address in 40A4H—40A5H to the value that it had prior to the first load. 
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From the above discussion it is apparent that locations 40F9I I— 40FAH contain an address that is important 
for locating a BASIC program. Indeed, this is so. In order to RUN a BASIC program, it is essential not only 
that 40A4H —40A5H contain the starting address, but also that 40F9H—40FAH contain an address 3 larger 
than that of the final byte of the BASIC program. (RUN will initialize the contents of 40FBH—40FCH and 
40FDH—40FEH to agree with the address in 40F9H—40FAH, which explains why we need not be concerned 
with the locations 40FBH— 40FEH.) 

When we load a BASIC program via CLOAD, the ending address plus 3 is determined by the CLOAD 
program and stored in 40F9H— 40FAH. Thus, under ordinary conditions, the address in 40A4H—40A5H is 
the onlv essential one lor loading and running a BASIC program. 

But suppose that you sneak your BASIC program in through a SYSTEM load, as you are soon going to 
learn how to do. In this case, the addresses in 40A4H —40A5I I and 40F9H— 40FAH both become crucial. The 
assembly language program that precedes the BASIC program on the system tape will know where the BASIC 
program begins — namely, exactly one byte beyond where the assembly language program ends. (Note that 
it will be necessary to terminate the assembly language program with a zero byte.) Hence, it will know the 
correct address to store in 40A4H—40A5H. There is a subroutine in ROM that will find the end of a BASIC 
program it locations 40A4H— 40A5H correctly tell it where the beginning is. Our assembly language prog¬ 
ram can use this routine to calculate the address to store in 40F9I I— 40FAH. The details will be given in 
Chapter 14. 
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CHAPTER 13 

Referencing BASIC Variables through VARPTR 


One of the main problems in linking separate programs is that of the passage of variables between them. 
The USR call allows a BASIC program to pass a single integer variable to an assembly language routine and to 
receive a single integer variable in return. (The assembly language routine receives its input in locations 
4121H—4122H and returns its output by loading it into HL and jumping to 0A9AH.) This, however, is too 
restrictive for general use. We need a method for passing variables back and forth on a more generous scale. 

The typical situation is that the assembly language routine needs several inputs from the BASIC program 
and that it returns several outputs to the BASIC program. This can be accomplished by using the VARPTR 
routine to find the addresses of the required BASIC variables and then employing these addresses cither to 
fetch input variables or to store output variables. (Of course, one pair of integer variables can still be ex¬ 
changed through the USR call.) The details of using VARPTR to find BASIC variable addresses have already 
been presented in Section 10.2. The following additional points should be clearly understood for successful 
variable passage by this method: 

(1) The assembly language routine needs to know the BASIC name and type (integer, string, single precision, 
or double precision) of each input and output variable that is not passed by the USR mechanism. For an array 
variable, the assembly language routine also needs to know the dimension numbers of the array. (You might 
compare this with FORTRAN subroutine linkage, in which the subroutine does not need to know the name of 
a variable being passed, but does need to know the type, the dimension numbers for an array variable, and the 
position of the variable name in the parameter list of the calling program.) 

(2) For a numeric variable, VARPTR returns the address of the first byte of the value of the variable. For a 
string variable, however, VARPTR returns the beginning address of the 3—byte “dope" block of the string; 
the starting address of the string itself is contained in the last two bytes of this block. 

(3) Once the assembly language routine has obtained the address of a variable, it may save that address for 
later use — so long as that later use occurs before control is returned to the BASIC program. Saving such an 
address from one execution of the subroutine to the next could prove fatal, since the BASIC program may 
move its variables around in their storage area. Therefore, the asembly language routine should find the 
address again (through VARPTR) whenever it is re-entered. 

(4) To thr BASIC program an assembly language subroutine will be essentially identical in appearance to a 
BASIC subroutine. The BASIC program knows that it needs to set up certain variables for the subroutine to 
operate upon, and it expects to find certain variable outputs when it regains control. The only difference is 
that the one' subroutine is activated by a USR call, while the other is activated by a GOSUB. 

(5) VARPTR will find the required address, but it is up to the assembly language program to fetch the (input) 
variable from that address, or to store the (output) variable at that address. This is merely a matter of 
transferring the correct number of bytes (for a numeric variable the number is 2, 4, or 8, depending upon 
variable type) as a block from one place in memory to another. The I.DIR instruction can be helpful for 
moving more than 2 bytes. Also, the procedure explained in Section 10.3 can be used for returning string 
variables to the BASIC program. 
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CHAPTER 14 

The Linkage Initialization Segment 


In order to execute a combined BASIC and assembly language program, certain initializations must be 
performed at, or just prior to, run time. Here is a list of the required preliminary operations: 

(1) The entry point address of the assembly language processing routine must be stored in locations 408EH — 

408FH in order to establish the linkage for the USR call. 

DISK SYSTEM NOTE: If you have a disk, the entry point address of the assembly language routine is 
ordinarily stored (by a DEFUSR command) in another location (in a table of such entry point addresses), from 
which it is transferred to 408EH —408FH at the time of execution of the USR call. In fact, DISK BASIC is quite 
intolerant of the storage of the entry point address in 408EII—408FH much before the subroutine is called. 
Therefore, readers with disk systems should not use the linkage initialization segment of this chapter. In 
Chapter 15 you will learn how to avoid the awkward DEFUSR command by keeping your own table of assembly 
language subroutine entry point addresses, from which the proper one will be transferred to408EH —40RFH at 
the time of the USR call. 

(2) If the BASIC program is loaded into memory above the assembly language program (which is the technique 

recommended in this book|, then the starting address for the BASIC segment must be stored in 
40A4H—40A5H. 

(3) If the BASIC program is recorded together with the assembly language program and loaded via the SYSTEM 

command (as is also recommended), then the ending address (of the BASIC segment) plus 3 must be 
stored in 40F9H—40FAH. 

While operation (1) above could be performed in the BASIC segment of the program, and operations (2) and 
(3) could be performed manually, it is most efficient to have a special assembly language routine (which will be 
called the "linkage initialization segment") perform all three operations automatically. The advantage of 
automatic execution of (2) and (3) over manual execution is indisputable. As for operation (1), the assembly 
language routine knows (through the operation of assembly) the address of its own entry point, while the 
BASIC program could only be told this after the assembly of the assembly language part. Thus, a reassembly of 
the assembly language routine might necessitate a change in the BASIC program il the latter set up the address 
in 408EH — 408FH by a POKE (or DEFUSR) command. 

The linkage initialization segment will be assembled and recorded just ahead of the assembly language 
processing routine, will be entered by running from the SYSTEM state, and will terminate by jumping to the 
RUN routine in ROM, causing the BASIC program to commence execution. Thus, the composite program can 
be loaded and executed in exactly the same manner as any machine language tape. 

The following annotated assembly language listing gives the details of the linkage initialization segment: 


ORC 

42E911 

Sec NOTE 1 

LD 

HL,ENTRY 

See NOTE 2 

LD. 

(408EH),HL 


LD 

HL, FINIS 

Sec NOTE 3 

LD 

(40A4H),HL 


LD 

DE,65530 

See NOTE 4 
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CALL 

1B2CH 

INC 

HL 

INC 

HL 

LD 

(40F9H),HL 

LD 

HL.1D1EH 

PUSH 

HL 

JP 

1B5DH 


See NOTE 5 


NOTE 1: The linkage initialization segment occupies the lowest available RAM. The origin of 42E9H is correct 

for a system with no disk. If you have a disk, do not use this linkage initialization segment-use the one in 

Chapter 15 instead. 

NOTE 2: The two instructions beginning with this line cause the entry point address (defined by the label 
"ENTRY") of the assembly language processing routine to be stored in 408EH—408FH, thus establishing the 
USR linkage. (The symbol "ENTRY" will, of course, appear somewhere as a label in the assembly language 
code that follows this initialization segment.) 

NOTE 3: The two instructions beginning with this line cause the starting address of the BASIC program 
segment to be stored in 40A4I I—40A5II. "FINIS" is the symbolic name of the location immediately following 
the final byte of the assembly language program. The last three lines of your assembly language program should 
be as follows: 


DEFB 0 

FINIS DEFS 0 

END 

Observe the terminating zero byte, which must precede the BASIC program to follow. The DEFS 0 gives the 
label "FINIS" the correct address value without reserving any memory for it. 

NOTE 4: The five instructions beginning with this line store the address of the end of the BASIC program plus 3 
in 40F9H—40FAH. The ROM routine at 1B2CH is the one (promised at the end of Chapter 12) that finds the 
end of the BASIC program. In order for the routine to do this, the beginning address of the BASIC program 
must be in 40A4H—40A5H, and the DE register pair must contain a line number larger than any in the BASIC 
program. These requirements have been satisfied by the three instructions preceding the CALL 1B2CH. Upon 
return from this routine, the HL register pair contains the desired end address plus 1. The two INC HL 
instructions ensure that the proper address will be stored in 40F9H—40FAH. 

NOTE 5: The three iristructions beginning with this line cause the BASIC program to be executed. (See Section 
10.7.) 


If you decide not to follow the advice to locate your assembly language routines in low core, you may still 
want to incorporate a linkage initialization segment with the assembly language part of a composite program. In 
this case, the segment needs to perform only operation (1) given at the beginning of this chapter, and it might 
terminate by a jump to the CLOAD routine so that the BASIC program would be loaded automatically. (The 
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operating proccdure would be a SYSTEM load, followed by a SYSTEM run, followed ultimately by a RUN from 
the READY state. The assembly language and BASIC programs would be recorded on separate but adjacent 
segments of the tape.) Here is a source listing for such an initialization segment for a diskless system: 



ORG 

7800H 

START 

LD 

HL,ENTRY 


LD 

(408EH),HL 


LD 

HL,ZBYT 


JP 

2C1FH 

ZBYT 

DEFB 

0 


The following notes are in explanation of the above listing: 

(1) The origin given is for illustration only. Choose the origin so that the assembly language routine will be 
located as high in memory as possible. (You need to know how long the assembly language program is before 
you can choose its best origin.) 

(2) The label "START” porvides a reference address for the END statement of the assembly. Thus, the 
statement 


END START 

terminating the assembly language program will result in the object program's being recorded with an entry 
point address corresponding to START. 

(3) "ENTRY" is again the symbolic name of the entry point of the assembly language processing routine, which 
follows the linkage initialization segment. 

(4) As explained in Section 7.3(a), the jump to 20 FH — with HL pointing to a zero byte — effects a CLOAD of 
the BASIC program. 
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CHAPTER 15 

USR Call Expansion 


A large program may need more than one assembly language subroutine; but in a diskless system there is 
only one USR call. A way around this limitation is to index the subroutines and to activate the desired one by 
using its index as the argument for the USR call. (For example, X% = USR(3) would call subroutine 3.) The 
assembly language program would examine the argument passed by the USR call and transfer control to the 
indicated subroutine. 

Another possible solution to the problem — and the one apparently intended by the designers of the 
TRS—80 software — is for the BASIC program to POKE (into 408EH—408FH) the address of each subroutine it 
needs just before calling it. But this is much too awkward, requiring, as it does, that the BASIC program know 
the memory address of every assembly language routine's entry point. 

If you have a disk, DISK BASIC provides 10 USR calls, which might seem to solve the problem. However, the 
efficient way to record the eptry point addresses in the table of such addresses is for each assembly language 
routine to store its own, rather than for the BASIC program to do it with DEFUSR commands. (This is so 
because the use of DEFUSR commands would still require the BASIC program to know the entry point address 
of every assembly language subroutine.) But DISK BASIC's table of subroutine entry point addresses may have 


different locations in different versions of DOS. It follows that the 

use of DISK BASIC's USR augmentation 

does not provide the ideal solution. 



With or without a disk, it is easy 

to increase the number of available USR calls (to a maximum of 10) in a 

manner that is consistent with the linkage procedures recommended in this book. The method for doing this is to 
expand the linkage initialization segment as shown in the following annotated listing. 

ORG 

42E9H 

See NOTE 1 

LD 

A.0C3H 

See NOTE 2 

LD 

(41 A9H),A 


LD 

HL,USRENT 


LD 

(41 AAH),HL 


LD 

HL,FINIS 


LD 

(40A4H),HL 


LD 

DE,65530 


CALL 

1B2CH 


INC 

HL 


INC 

HL 


LD 

(40F9H),HL 


LD 

HL.1D1EH 


PUSH 

HL 


JP 

IB5DI1 


USRENT RST 

10H 

See NOTE 3 

JP 

NC,1997H 


PUSH 

HL 


SUB 

30H 


CP 

3 

See NOTE 4 

JP 

NC.1997H 


LD 

L,A 

See NOTE 5 
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LD 

H,() 


ADD 

HL,HL 


LD 

DE,JPTBL 


ADD 

HL,DE 


LD 

E.(HL) 

See NOTE 6 

INC 

HL 


LD 

D,(HL) 


LD 

(408EH),DE 


POP 

HL 

Sec NOTE 7 

RET 

DEFW 

ENTRY1 

Sec NOTE 8 

DEFW 

LNTRY2 


DEFW 

ENTRY3 



NOTE 1: The origin given is fora diskless system. If you have a disk, use a higher origin — 7000H is a good one. 
Observe that this linkage initialization segment is recommended for multiple USR calls even if you have a disk. 
This segment bypasses (and substitutes for) the USR augmentation of any disk system. (If you have a disk and 
need only one USR call, use the above segment with only one JPTBL entry.) Use of 7000H as the starting 
address for your assembly language routine in a system with a disk provides a margin of safety against future 
POS enlargements and also allows you to record your program on disk with either a DUMP or TAPEDISK 
command. Once the program is on disk, it can be recalled by a LOAD command and can then be run by returning 
to BASIC and using the SYSTEM command. (It won't run immediately after a transfer to memory from disk, 
because the BASIC part of it requires the DISK BASIC overlay. However, if you have NEWDOS, the program 
can be loaded and executed directly from BASIC.) 

NOTE 2: The four instructions beginning with this line store a jump to USRENT in 41A9H—41ABH, causing 
the USR routine in ROM to call the routine above starting at USRENT. The next ten instructions in the above 
initialization segment are unchanged from Chapter 14. 

NOTE 3: The two instructions beginning with this line check for a syntax error. The “USR" command in your 
BASIC program must be followed immediately by a digit from 0 to 9. ("USR" without an ending digit is 
permitted in DISK BASIC in lieu of "USRO". The above augmentation does not permit "USR" without the 
terminating digit.) 

NOTE 4: The digit after the "USR" must not exceed one less than the number of entries in JPTBL. In this 
example there are three entries in JPTBL, and the digit is compared with 3. If there were 7 entries in JPTBL, the 
CP instruction would be CP 7. (A syntax error occurs if the digit following the "USR" is too large.) 

NOTE 5: The five instructions beginning with this line compute the address (within the JPTBL) at which the 
required entry point address is stored. 

NOTE 6: The four instructions beginning with this line transfer the entry point address of the desired 
subroutine from the JPTBL to locations 408EH—408FH. 

NOTE 7: The two instructions beginning with this line effect a graceful return to the USR routine in ROM. 
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NOTE 8: The JPTBL contains the (symbolic) entry point addresses of the several (three in this example) 
assembly language subroutines corresponding to the calls USRO, USR1, USR2,etc. The JPTBL addresses can be 
symbolic as long as all the subroutines and the linkage initialization segment are assembled together. When this 
is impracticable (perhaps due to memory limitation in using the Editor/Assembler), a somewhat more elaborate 
structure — to be explained in the next chapter — is required. 
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CHAPTER 16 

Linking Multiple Assembly Language Segments 


Suppose that you have written a combined BASIC and assembly language program that has several assembly 
language subroutines. In Chapter 15 you learned how to expand the number of USR calls so that the different 
subroutines would have different calls. If all the subroutines and the linkage initialization segment can be 
combined into one assembly, you have no further linkage problems. In a I6K machine the largest program that 
can be assembled by the TRS—80 Editor/Asscmbler is about 1000 bytes, and this estimate assumes that there 
are no space—consuming remarks. Now 1000 bytes are enough for most of the assembly language programs 
that you will write, but some of your programs may exceed this limit. In that case the assembly language 
subroutines may have to be assembled in two or more separate units, and there is then the problem of linking 
these units. 

A simple solution to this linkage problem involves dividing the linkage initialization segment among the 
several separate assemblies. Conceptually, the scheme works as follows: At run time, the first assembly is 
activated, and it stores a jump to the USR expansion routine in 41A9U—41ABH. Then control and a pointer to 
the second JPTBL location are passed to the second assembly, which stores its subroutine entry point address in 
the second JPTBL location. This daisy-chaining continues up to the last assembly, which stores its subroutine 
entry point address in the last JPTBL location, completes the linkage initialization procedure, and finally jumps 
to the RUN routine in ROM to cause the BASIC program to commence execution. 

There is one flaw in the above scheme: Each assembly language segment except the last must know the origin 
of the next segment in the chain. There is no obvious way to eliminate this flaw, but its effect can be minimized. 
After the assembly language segments have been written, determine their lengths and allow an extra 50 or so 
bytes for each one. Then, starting from origin 42E9H (or higher, with a disk), firm origins can be established for 
all of the segments. The resulting program will occupy slightly more memory than necessary, but you will gain 
two advantages: 

(1) Each segment will have its own space for patching during the debugging phase. 

(2) Each subroutine can be reassembled independently of all the others, provided that its reassembled length is 

not too much greater than its original length. 

The following annotated listing illustrates the linkage procedure for three assembly language segments. 


USRENT 



ASSEMBLY 1 

ORG 

42E9H 

LD 

A.0C3H 

LD 

(41A9HJ.A 

LD 

HL,USRENT 

LD 

(41 AAH),HL 

LD 

HL.JPTBL+2 

JP 

4600H 

RST 

10H 

JP 

NC.1997H 

PUSH 

HL 

SUB 

30H 


See NOTE 1 
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JPTBL 


CP 

3 


JR 

NC.1997H 


LD 

L,A 


LD 

H,0 


ADD 

HL,HL 


LD 

DE, JPTBL 


ADD 

HL,DE 


LD 

E,(HL) 


INC 

HL 


LD 

D,(HL) 


LD 

(408EH),DE 


POP 

HL 


RET 

DEFW 

ENTRY1 

See NOTE 2 

DEFS 

2 


DEFS 

2 




ASSEMBLY 2 


ORG 

4600H 


LD 

BC,ENTRY2 

See NOTE 3 

LD 

(HL),C 


INC 

HL 


LD 

(HL),B 


INC 

HL 

See NOTE 4 

JP 

4900H 




ASSEMBLY 3 


ORG 

4900H 


LD 

BC,ENTRY3 

See NOTE 5 

LD 

(HL),C 


INC 

HL 


LD 

(HL),B 


LD 

HL,FINIS 

■ See NOTE 6 

LD 

(40A4H),HL 


LD 

DE,65530 


CALL 

1B2CH 


INC 

HL 


INC 

HL 


LD 

(40F9H),HL 


LD 

HL,1D1EH 


PUSH 

HL 


JP 

1B5DH 
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riNis 


DEFB 

nrjs 

END 


0 

n 


Sec NOTE 7 


NOTE 1: The HL register pair is loaded with a pointer to the second JPTBL location; the correct value is 
JPTBL+2 because the addresses stored in JPTBL each occupy 2 bytes. The JP 46(X)H instruction in the next line 
presupposes that the second assembly language segment begins at 460011. (In practice the correct address here is 
determined by finding the length of the first segment, padding it a bit, and adding the total to the origin of the 
first segment.) 

NOTE 2: The JPTBL already contains the (symbolic) entry point address of the subroutine in the first assembly 
language segment; The entry point addresses of the subroutines in the later segments will be stored in the table 
by those segments. The table has just enough room for those addresses. 

NOTE 3: The four instructions beginning with this line store the entry point address of the subroutine in the 
second assembly language segment at the second JPTBL location, which is pointed to by the HL register pair. 
(Compare with NOTE 1.) 

NOTE 4; HL is incremented so that it points to the third location in the JPTBL. Control then passes to the third 
assembly language segment at 4900H. 

NOTE 5: The four instructions beginning with this line store the entry point address of the subroutine in the 
third assembly language segment at the third JPTBL location. 

NOTE 6: The ten instructions beginning with this line complete the linkage initialization procedure, culminat¬ 
ing in a jump to RUN. (Compare with the listings of Chapters 14 and 15.) 

NOTE 7: Again we see the mandatory zero byte just before the BASIC program. 

If you have a disk, the above sample listing needs to be changed in only two respects: 

(1) The origins of the three assemblies would be higher. 

(2) In each of the first two assemblies the jump to the origin of the next assembly would have to be modified to 
conform to the higher origin ol the next assembly. 

Observe once more that it is recommended that you use the above linkage procedure either with or without a 
disk. If you have a disk, the given USR expansion substitutes for the USR augmentation of DISK BASIC. 


With this recommended structure, it also becomes possible for any of your assembly language subroutines to 
call an assembly language subroutine in any other segment. The following annotated listing shows how this can 
be done. 
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LD 

HL,SRNUM—1 



CALL 

41A9H 



LD 

HL,(ARG) 

See NOTE 8 


LD 

(4121H),HL 



CALL 

2815H 


SRNUM 

DEFB 

'2' 

See NOTE 9 


NOTE 8: The two instructions beginning with this line are used to pass an integer argument — assumed to be 
stored in two bytes starting at the symbolic address ARG — to the subroutine being called. If no argument is to 
be passed, these instructions may be omitted. If the called subroutine ordinarily returns an integer value 
through the USR mechanism, that value will be found in 4121H—4122H and in HL. 


NOTE 9: The setup at symbolic address SRNUM (for “subroutine number") is for calling the subroutine that 
the BASIC program would call by USR2. For the subroutine called by USR5, the byte defined here should be '5', 
etc. 
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CHAPTER 17 

Taping, Loading, and Executing Composite Programs 


Let us assume that you have written a composite program using the linkage methods that have been described 
in the preceding chapters. Here are the steps to follow in putting it all together. 

(1} Assemble and debug each assembly language segment separately and record the object code. Make a note of 
the address of the "I'lNIS" label in the final segment. 

(2) Write, debug, and record the BASIC program segment. 

(3) Load all the assembly language segments into memory via the SYSTEM command. Also, load a machine 
language monitor with SYSTEM recording capability (such as MicroMind) into the high end of memory. 

(4) POKE the ending address plus 1 of the last assembly language segment into 40A4H—40A5H. (Or use the 
machine language monitor to do it. This address is that of the "FINIS" label, saved from step (1).) 

(5) Load the BASIC program via the CLOAD command. 

(6) Use the machine language monitor to record the composite program on tape. The starting address for this 
recording will be the origin of the first assembly language segment, the ending address will be the address that 
you find in 40F9H—40FAH, and the entry point address will also be the origin of the first assembly language 
segment. Give your program whatever name you choose. 

Now you have your composite program recorded as a single segment on tape in a SYSTEM compatible 
format. To load and execute this tape, use the SYSTEM command, type the name of your program, and press 
ENTER. When the tape has been loaded, type "/" and press ENTER. 

What if you discover errors in your program now? If an error is found in the BASIC segment, correct it<in the 
usual way. (You will find that the BASIC program can be LlSTed and EDITed as usual after the composite 
program has been run once. Do not try to LIST before running the composite program.) Then record the entire 
program again with the machine language monitor, using the new address in 40F9H—40FAH as the ending 
address. 

DISK SYSTEM NOTE: With TRS—DOS, editing of a composite program may occasionally result in 
"INTERNAL ERROR" and a reinitialization of DOS. This sporadic error seems to depend upon the location in 
memory of the line being edited. If a particular edit seems to be impossible to accomplish in the composite 
program, perform it on the separate BASIC program segment and then rctape the entire program. 

If an error is discovered in an assembly language segment, it can be patched, provided that you have left some 
room at the end of the segment for this purpose. Then record the entire program again. Or, if you wish, this 
segment can be reassembled without modifying any of the other segments, as long as its new length does not 
exceed the original space allocation for the segment. In case of a reassembly, reload the composite program, then 
load the new assembly and retape the entire program. (Note that the final segment can be reassembled at will, 
since an increased length for it will merely cause a relocation of the BASIC segment without affecting any of the 
linkages. Of course, to retape after such a reassembly would require reloading the composite program, followed 
by the reassembled final assembly language segment and the BASIC segment.) 
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Modifications or augmentations of any of the segments can be handled exactly like errors. However, if an 
augmentation of any assembly language segment except the last one causes that segment to exceed its original 
space allocation, then all subsequent assembly language segments will have to be reassembled with new origins. 
(Nothing changes in any of these segments except their origins and the forward jump addresses in their linkage 
initialization segments.) 

As has been mentioned above, once the composite program has been run from the SYSTEM state, the BASIC 
program can be both LISTed and EDITed. It can also be RUN, which means that it is unnecessary to reenter the 
SYSTEM state to rerun the composite program. (The linkage initialization segments need to perform their 
function only once — when the program is first loaded.) 

If you have a disk, the composite program can be loaded via the SYSTEM command and then saved on disk by 
a DUMP, provided that you have given its first segment an origin of 7000H or higher. Once the program is on 
disk, it can be recalled by a LOAD and can be run by returning to BASIC and using the SYSTEM command. (It 
won't run immediately after a transfer to memory from disk, because the BASIC part of it requires the DISK 
BASIC overlay. However, if you have NEWDOS, the program can be loaded and executed directly from 
BASIC.) 

DISK SYSTEM NOTE: The DISK SYSTEM CAUTIONs of Part I of this book detailed the special precautions 
that must be taken in using some of the ROM subroutines in assembly language programs that may be executed 
in the absence of the DISK BASIC overlay. Since the composite programs of Part II require the presence of DISK 
BASIC, all the ROM subroutines of part I may be used in these composite programs without any special 
precautions. 
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CHAPTER 18 

An Example of a Composite Program 


In this final chapter is given an example of a complete program constructed with the techniques explained in 
this book. The program computes any positive (integral) power up to the 500th of any positive integer up to 
7392 and displays all the digits. Input is processed by the BASIC program segment, while the calculations are 
done in assembly language for maximum speed. (As an example, 137 to the power of 20 is computed in about 
half a second by this program, while an equivalent all—BASIC program would take about 20 seconds for the 
same calculation.) Output of the multi—digit result is also done in an assembly language subroutine; this 
feature is not absolutely necessary for speed of execution but has been included to illustrate the linkage of two 
separate assembly language routines to a BASIC program. 

In studying this example, pay particular attention to the linkage initialization segments, the USR call 
expansion, and the use of VARPTR and the USR calls themselves to pass variables between the BASIC and 
assembly language programs. Here is the annotated listing: 

ASSEMBLY 1 


00100 


0RG 

42E9H 



00110 


LD 

A, 0C3H 



00120 


L0 

(41A9H), A 



00130 


LO 

HL, USRENT 



00140 


LO 

(41AAH), H L 



00150 


LD 

HL, JPTBL+2 



00160 


JP 

4400H 

;See NOTE 

1 

00170 

USRENT 

RST 

10H 



00180 


JP 

NC,1997H 



00190 


PUSH 

HL 



00200 


SUB 

30H 



00210 


CP 

2 



00220 


JP 

NC, 1997H 



00230 


LD 

l,A 



00240 


LD 

H, 0 



00250 


ADD 

HL,HL 



00260 


LD 

DE,JPTBL 



00270 


ADD 

HL, DE 



00280 


LD 

E, (HL) 



00290 


INC 

HL 



00300 


L0 

D, (HL) 



4)0310 


L0 

( 408EH),DE 



00320 


POP 

HL 



00330 


RET 




00340 

JPTBL 

DEFW 

ENTRY1 



003 50 


DEFS 

2 



00360 

ENTRY1 

L0 

HL, (4121H) 

;See NOTE 

2 

00370 


LD 

( NHLD), HL 



00380 


L0 

HL,ENAM 

;See NOTE 

3 

00390 


CALL 

26 0DH 



00400 


EX 

DE, HL 



00410 


LD 

E, (HL) 



00420 


INC 

HL 



00430 


LD 

D, (HL) 



00440 


L0 

(EHLD),DE 



00450 


L0 

HL, PWNAM 



00460 


CALL 

26 0DH 



00470 


LD 

(PWPNT),DE 



00480 


LD 

HL, -1 



00490 


LD 

(0HLD),HL 



00500 


L0 

DE,(NHLD) 



00510 


CALL 

SPREAD 

;See NOTE 

4 


55 — 



00520 


LD 

BC, 1 




00530 

LOOP1 

PUSH 

BC 

;See 

NOTE 

5 

00540 


LD 

BC, 0 




00550 


LD 

D, B 




00SE0 


LD 

E, C 




00570 

LOOP2 

PUSH 

BC 




00580 


LD 

HL,(PWPNT) 




00590 


ADD 

HL, BC 




00600 


LD 

(PWI ND),HL 




00610 


LD 

B, (HL) 




00620 


PUSH 

DE 




00630 


LD 

DE,(NHLD) 




00640 


LD 

HL, 0 




00650 


LD 

A, B 




00660 


OR 

A 




00670 


JR 

Z, OUT 




00680 

LOOP3 

ADD 

HL, DE 

;See 

NOTE 

6 

00690 


D JNZ 

LOOPS 




00700 

OUT 

POP 

BC 




00710 


ADO 

HL, BC 




00720 


CALL 

DIVIO 

;See 

NOTE 

7 

00730 


LD 

A, H 




00740 


LD 

HL,( PWIND) 




00750 


LD 

(HL), A 




00760 


POP 

BC 




00770 


LD 

HL, (DHLD) 




00780 


OR 

A 




00790 


SBC 

HL, BC 




00800 


INC 

BC 




00810 


JR 

NZ,L00P2 




00820 


CALL 

SPREAD 

iSee 

NOTE 

4 

00830 


POP 

BC 




00840 


INC 

BC 




00850 


LD 

HL,(EHLD) 




00860 


OR 

A 




00870 


SBC 

HL, BC 




00880 


JR 

NZ,L00P1 




00890 


LD 

HL, (DHLD) 

; See 

NOTE 

8 

00900 


JP 

0A9AH 




00910 

SPREAD 

LD 

A, D 

; See 

NOTE 

4 

00920 


OR 

E 




00930 


RET 

Z 




00940 


EX 

DE,HL 




00950 


CALL 

DIVIO 

; See 

NOTE 

7 

00960 


LD 

A,H 




00970 


LD 

HL, (DHLD) 




00980 


INC 

HL 




00990 


LD 

(DHLD),HL 




01000 


LD 

BC,(PWPNT) 




01010 


ADD 

HL, BC 




01020 


LD 

(HL),A 




01030 


JR 

SPREAD 




01040 

DIVIO 

LD 

DE, 0 

;See 

NOTE 

7 

01050 


LD 

C,10 




01060 


LD 

A,H 




01070 


DEC 

D 




01080 

A.00P4 

INC 

D 




01090 


SUB 

C 




01100 


JR 

NC, L00P4 




OHIO 


ADO 

A.C 




01120 


LO 

H, A 




01130 


LD 

B, 8 




01140 

L00P5 

ADD 

HL, HL 




01150 


RLC 

E 




01160 


LO 

A,H 




01170 


SUB 

C 




01180 


JR 

C, Nl X 




01190 


LD 

H, A 




01200 


INC 

E 





56 



01210 

01220 

NIX 

DJNZ 

RET 

L00P5 

01230 

EHL0 

OEFS 

2 

0121(0 

PWPNT 

DEFS 

2 

012SO 

OHLD 

DEFS 

2 

01260 

NHLD 

DEFS 

2 

01270 

PWINO 

DEFS 

2 

01280 

ENAM 

DEFB 

•E ’ 

01290 


OEFB 

0 

01300 

PWNAM 

DEFM 

'PW(O)' 

01310 

01320 


OEFB 

ENO 

0 


NOTE 1: 4400H is the origin of Assembly 2. (If you have a disk, both assemblies would have higher origins.) It 
was chosen so as to leave about 50 bytes of free memory at the end of Assembly 1. When Assembly 1 was being 
debugged, this free space proved valuable for patching. 

NOTE 2: The two instructions beginning with this line retrieve the value of the integer variable N (passed by the 
USRO call in the BASIC program) and store it locally at NHLD. 

NOTE 3: The ten instructions beginning with this line use VARPTR twice to (1) fetch the value of the BASIC 
variable E and store it locally at EHLD, and (2) fetch the beginning address of the (BASIC) PW array and store it 
locally at PWPNT. 

NOTE 4: SPREAD is the entry point of a subroutine that separates the digits of the integer in the DE register 
pair and stores these digits in separate bytes of the PW array. 

NOTE 5: The 36 instructions beginning with this line form a nest of three loops that multiply N by itself (digit 
by digit) E— 1 times and store the digits in the PW array. Observe the use of the stack (the PUSHes and POPs) 
for efficient handling of the loop counters for loops 1 and 2. 

NOTE 6: The two—instruction loop beginning with this line performs a fast multiplication of the integer N by 
the digit in the B register. 

NOTE 7: DIVID is the entry point of a subroutine that performs a fast division by 10. The dividend is passed to 
the subroutine in the HL register pair, and the quotient and remainder are returned in the DE and A registers, 
respectively. 

NOTE 8: The two instructions beginning with this line effect a return to the BASIC program and the passage of 
the value of the integer variable D to that program. (The value of D is .one less than the number of digits in N to 
the power of E.) 
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ASSEMBLY 2 


00100 


ORG 

6600H 




00110 


LD 

BC.ENTRY2 




00120 


LO 

(HL).C 




00130 


INC 

HL 




0014 0 


LD 

(HL),B 




00150 


L0 

HL, F1 N1 S 




00160 


LO 

(6 0A6H) ,HL 




00170 


L0 

DE.65530 




00180 


CALL 

1B2CH 




00190 


INC 

HL 




00200 


INC 

HL 




00210 


L0 

(60F9H),HL 




00220 


LD 

HL, 1D1EH 




00230 


PUSH 

HL 




00260 


JP 

1B50H 




00250 

ENTRY2 

L0 

HL,(6121H) 

;See 

NOTE 

9 

00260 


PUSH 

HL 




00270 


LD 

HL,PWNAM 

; See 

NOTE 

10 

00280 


CALL 

26 0DH 




00290 


L0 

(PWPNT),DE 




00300 


POP 

DE 

jSee 

NOTE 

11 

00310 

LOOP 

PUSH 

DE 

jSee 

NOTE 

12 

00320 


L0 

HL, (PWPNT) 




00330 


ADD 

HL, DE 




00360 


LO 

A, (HL) 




00350 


A00 

A, 30H 




00360 


L0 

HL,STROUT 




00370 


LO 

(HL),A 




00380 


CALL 

28A7H 




00390 


POP 

DE 




00600 


LD 

A, 0 




00610 


OR 

E 




00620 


JP 

Z,0A9AH 

;See 

NOTE 

13 

00630 


DEC 

0E 




00660 


JR 

LOOP 




00650 

PWNAM 

DEFH 

'PW(O) ' 




00660 


0EFB 

0 




00670 

PWPNT 

DEFS 

2 




00680 

STROUT 

DEFS 

1 




00690 


0EFB 

0 




00500 


OEFS 

50 




00510 


0EFB 

0 




00520 

FINIS 

DEFS 

0 




00530 


END 






NOTE 9: The two instructions beginning with this line retrieve the value of the integer variable D (passed by the 
USR1 call in the BASIC program) and store it on the stack. 

NOTE 10: The three.instructions beginning with this line fetch the starting address of the PW array (using 
VARPTR) and store it locally at PWPNT. 

NOTE 11: Here the value of D is retrieved from the stack. (See NOTE 9.) 

NOTE 12: The 14 instructions beginning with this line form a loop that prints the digits in the PW array. The 
digits are fetched from thePW array one at a time — starting with the high end, and proceeding to the low end of 
the array — and are printed individually by the ROM routine at 28A7H. (See Section 8.2 (b).) 

NOTE 13: When all the digits have been printed, control returns to the BASIC program. The instruction JP 
Z.0A9AH is used rather than RET Z because the routine at 28A7H leaves a 3 in 40AFH. (See Section 8.2 (b).) 


— 58 — 



BASIC SEGMENT 


100 OEFIMT A-Z:01M PU(IOOO) 

110 CIS 

120 PRINT "A PROGRAM TO RAISE NUMBERS TO POWERS" 
ISO PRINT: INPUT "NUMBER";?! 

HO IF N>0 AMD N<7593 THEN 160 

150 PRINT "ILLEGAL NUMBER":GOTO 130 

160 INPUT "POWER"; E 

170 IF E>0 ANO E<SO 1 THEN 190 

180 PRINT "ILLEGAL POWER":GOTO 160 

190 IF E*1 THEN 210 

200 O-IJSRO(N) 

210 PRINT 

220 PRINT N;"TO THE POWER OF";E;"IS:" 

230 PRINT 

2LO IF E-l THEN 280 
250 X-USRl(O) 

260 PR I NT:PR I NT:INPUT AJ 
270 CLS:GOTO 130 
28 0 PRINT N: GOTO 260 
290 END 
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APPENDIX 1 

Hex—Decimal Conversion Table 


The table which follows is a useful tool for converting numbers between base 10 (decimal) and base 16 
(hexadecimal). This ability is often required in programming. The table consists of 12 columns of numbers, in 4 
groups of three. Within each group of three, the first column is a single byte hexadecimal value. The second 
column is the high order decimal equivalent of the hex byte, and the third column is the low order decimal 
equivalent of the hex byte. 

To convert a single byte hex value to decimal, just find the 2 digit hex value in the first column and read its 
equivalent in the third column. 

EXAMPLE: To convert AFH to decimal, find it in the first column. It corresponds to 175 in the third column. 

To convert a 4 digit hex number to decimal, find the 2 digit high order byte in the first column. Its decimal 
value is shown in the middle column. Write this number down. Now find the 2 digit low order byte in the first 
column and read its decimal equivalent in the third column. The sum of these two decimal numbers is the 
decimal value of the two byte hexadecimal number. 

EXAMPLE: To convert 1A19H to decimal, find 1A in the first column. It corresponds to 6656 in the middle 
column. Then find 19 in the first column and its equivalent in the third column, 25.1A19H is the same 
as 6656+25 or 6681 (decimal). 

Toconvert a decimal number smaller than 256 to hex, find it in the third column. The hexadecimal equivalent 
will be found in the first column. If the decimal number is larger than 256, find the largest decimal number in 
the middle column which is smaller than or equal to the number in question. The corresponding hexadecimal 
byte in the first column is the high order hex value of the decimal number. Now find the difference between this 
decimal number and the original one. The hex value corresponding to this number (which should be less than 
256) is the low order byte of the hex equivalent. 

EXAMPLE: Toconvert 16429 to hexadecimal notation, find 16384 in the middle row. It is smaller than 16429, 
and the next number in the middle row is larger than 16429. The hexadecimal equivalent of 16384 is 
40, and this is the high order half of the hex number. Now subtract 16384 from 16429. The difference 
is 45, which corresponds to a hex value of 2D. The hexadecimal equivalent of 16429 is therefore 
402DH. 

The high order values of the four major groups of three columns can be seen to correspond to the 16K 
increments of the TRS—80 computer memory. The first group (from 0 to 3F00H) represents the ROM, 
keyboard, and video areas. The second group represents the extent of a 16K machine and the third group a 32K 
machine. A 48K machine contains memory in all locations shown on this table. This visualization is sometimes 
useful in understanding the positioning of programs and hardware in the TRS—80. 
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Hex—Decimal Conversion Table 


HfX 

DECI 

IMAL 

HEX 

_decimal 

HEX 

DEC 

IMAL 

HEX 

npri mai 

00 

0 

0 

40 

16384 

64 

80 

32768 

128 

CO 

49152 

192 

01 

256 

1 

41 

16640 

65 

81 

33024 

129 

Cl 

49408 

193 

02 

512 

2 

42 

16896 

66 

82 

33280 

130 

C2 

49664 

194 

03 

768 

3 

43 

17152 

67 

83 

33536 

131 

C3 

49920 

195 

04 

1024 

4 

44 

17408 

68 

84 

33792 

13 2 

C4 

50176 

196 

OS 

1280 

5 

45 

17664 

69 

85 

34048 

133 

C5 

50432 

197 

06 

1536 

6 

46 

17920 

70 

86 

34304 

134 

C6 

50688 

198 

07 

1792 

7 

47 

18176 

71 

87 

34560 

135 

C7 

50944 

199 

06 

2048 

8 

48 

18432 

72 

88 

34816 

136 

C8 

51200 

200 

09 

2304 

9 

49 

18688 

73 

89 

35072 

137 

C9 

51456 

201 

3 A 

256 0 

10 

4 A 

18944 

74 

8 A 

35328 

138 

CA 

51712 

202 

08 

2816 

11 

4 B 

19200 

75 

88 

35584 

139 

CB 

51968 

203 

OC 

3072 

12 

4C 

19456 

76 

8 C 

35840 

140 

CC 

52224 

204 

0D 

3328 

13 

4 D 

19712 

77 

8D 

36096 

141 

CD 

52480 

205 

0E 

3584 

14 

4E 

19968 

78 

8 E 

36352 

142 

CE 

52736 

206 

OF 

3840 

15 

4F 

20224 

79 

8F 

36608 

143 

CF 

52992 

207 

10 

4096 

16 

50 

20480 

80 

90 

36864 

144 

DO 

53248 

208 

11 

43 52 

17 

51 

20736 

81 

91 

37120 

145 

D1 

53504 

2 09 

12 

4608 

18 

52 

20992 

82 

92 

37376 

146 

D2 

53760 

210 

13 

4864 

19 

53 

21248 

83 

93 

37632 

147 

D3 

54016 

211 

14 

5120 

20 

54 

21504 

84 

94 

37888 

148 

D4 

54272 

212 

IS 

5376 

21 

55 

21760 

85 

95 

38144 

149 

D5 

54528 

213 

16 

5632 

22 

56 

22016 

86 

96 

38400 

150 

D6 

54784 

214 

17 

5888 

23 

57 

22272 

87 

97 

38656 

151 

D7 

55040 

215 

18 

6144 

24 

58 

22528 

88 

98 

38912 

152 

D8 

55296 

216 

19 

6400 

25 

59 

22784 

89 

99 

39168 

153 

D9 

55552 

217 

1A 

6656 

26 

5 A 

23040 

90 

9 A 

39424 

154 

DA 

55808 

218 

IB 

6912 

27 

5B 

23296 

91 

98 

39680 

155 

DB 

56064 

219 

1C 

7168 

28 

5C 

23552 

92 

9C 

39936 

156 

DC 

56320 

220 

10 

7424 

29 

50 

23808 

93 

9D 

40192 

157 

DD 

56576 

221 

IE 

7680 

30 

5E 

24064 

94 

9E 

40448 

158 

DE 

56832 

222 

IF 

7936 

31 

5F 

24320 

95 

9F 

40704 

159 

DF 

57088 

223 

20 

8192 

32 

60 

24576 

96 

A0 

40960 

160 

EO 

57344 

224 

21 

8448 

33 

61 

24832 

97 

A1 

41216 

161 

El 

57600 

225 

22 

8704 

34 

62 

25088 

98 

A2 

41472 

162 

E2 

57856 

226 

23 

8960 

35 

63 

25344 

99 

A3 

41728 

163 

E3 

58112 

227 

24 

9216 

36 

64 

25600 

100 

A4 

41984 

16 4 

E4 

58368 

228 

25 

9472 

37 

65 

25856 

101 

AS 

42240 

165 

E5 

58624 

229 

26 

9728 

38 

66 

26112 

102 

A6 

42496 

16 6 

E6 

58880 

230 

27 

9984 

39 

67 

26368 

103 

A7 

42752 

167 

E7 

59136 

231 

28 

10240 

40 

68 

26624 

104 

A8 

43008 

168 

E8 

59392 

232 

29 

10496 

41 

69 

26880 

105 

A9 

43264 

169 

E9 

59648 

233 

2 A 

10752 

42 

6 A 

27136 

106 

AA 

43520 

170 

EA 

59904 

234 

28 

11008 

43 

6B 

27392 

107 

AB 

43776 

171 

EB 

60160 

235 

2C 

11264 

44 

6C 

27648 

108 

AC 

44032 

172 

EC 

60416 

236 

2D 

11520 

45 

6 D 

27904 

109 

AD 

44288 

173 

ED 

60672 

237 

2E 

11776 

46 

6E 

28160 

110 

AE 

44544 

174 

EE 

60928 

238 

2F 

12032 

47 

6 F 

28416 

111 

AF 

44800 

175 

EF 

61184 

239 

30 

12288 

48 

70 

28672 

112 

BO 

450S6 

176 

FO 

61440 

240 

31 

12544 

49 

71 

28928 

113 

81 

45312 

177 

FI 

61696 

241 

32 

12800 

50 

72 

29184 

114 

82 

45568 

178 

F2 

61952 

242 

33 

13056 

51 

73 

29440 

115 

B3 

45824 

179 

F3 

62208 

243 

34 

13312 

52 

74 

29696 

116 

B4 

46080 

180 

F4 

62464 

244 

35 

13568 

53 

75 

29952 

117 

85 

46336 

181 

F5 

62720 

245 

36 

1382 4 

54 

76 

30208 

118 

B6 

46592 

18 2 

F6 

62976 

246 

37 

14080 

55 

77 

30464 

119 

87 

46848 

183 

F7 

63232 

247 

38 

14336 

56 

78 

30720 

120 

B8 

47104 

184 

F8 

63488 

248 

39 

14592 

57 

79 

30976 

121 

89 

47360 

185 

F9 

63744 

249 

3A 

14848 

58 

7A 

31232 

122 

BA 

47616 

186 

FA 

64000 

250 

38 

15104 

59 

7B 

31488 

123 

BB 

478 72 

187 

FB 

64256 

251 

SC 

15360 

60 

7C 

31744 

124 

BC 

48128 

188 

FC 

64512 

252 

3D 

15616 

61 

7D 

32000 

125 

BD 

48384 

189 

FD 

64768 

253 

3E 

15872 

62 

7E 

32256 

126 

BE 

48640 

190 

FE 

65024 

254 

3F 

16128 

63 

7F 

32512 

127 

BF 

48896 

191 

FF 

65280 

255 
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APPENDIX 2 

A Program to Record Composite Tapes 


The assembly language program given below will record a SYSTEM tape of a composite (BASIC and assembly 
language) program constructed in accordance with the directions given in Part II of this book. The origin and 
execution address of the tape it creates will be 42E9H (the beginning of free RAM in Level II). The program 
automatically dumps from this address to the end of any resident BASIC program. (The assembly language 
segments and the BASIC program segment should be loaded into memory as explained in Chapter 17. Then the 
following routine will correctly record the composite program. Observe the generous use of ROM subroutines 
in this program.) 


00100 


0RG 

7F6 0H 


00110 

START 

CALL 

01C9H 

;CLEAR SCREEN 

00120 


LD 

HL,TEXT 


00130 


CALL 

28A7H 

;DISPLAY PROMPT 

OOlbO 


LD 

HL, 41E8H 


00150 


PUSH 

HL 


00160 


LD 

B,6 


00170 

FILL 

LD 

(HL),20H 

;SPACES IN BUFFER 

00180 


INC 

HL 


00190 


DJNZ 

FILL 


00200 


POP 

HL 


00210 


LD 

8,6 


00220 


CALL 

05D9H 

;INPUT TITLE 

00230 


X0R 

A 


00240 


CALL 

0212H 

;CASSETTE ON 

00250 


CALL 

0287H 

;WRITE LEADER 

00260 


LD 

A, 55H 

;10 BYTE 

00270 


CALL 

0264H 


00280 


LD 

HL,41E8H 

;ADDRESS OF TITLE 

00290 


LD 

8,6 


00300 

NAME 

LD 

A,(HL) 


00310 


CP 

0DH 

;1S IT A C. R.? 

00320 


JR 

NZ,SK1P 


00330 


LD 

A, 20H 

;CHANGE TO SPACE 

00340 

SKIP 

CALL 

0264H 

;WRITE BYTE 

00350 


INC 

HL 


00360 


DJNZ 

NAME 

;LOOP FOR 6 CHARS 

00370 


LD 

HL, 42E9H 

.•♦START ADDRESS* 

00380 

LP1 

LD 

DE, 0 

;BYTE COUNT 

00390 


LD 

c,0 

;CLEAR CHECKSUM 

00600 


LD 

A, 3CH 

;BLOCK SYNC 

00410 


CALL 

0264H 


00420 


L0 

A, E 

;BYTE COUNT 

00430 


CALL 

0 26 4H 


00440 


LD 

A,L 

;AODRESS OF DATA 

00450 


CALL 

0264H 


00460 


LD 

A, H 

;ADDRESS OF DATA 

00470 


CALL 

0264H 


00480 


ADO 

A, L 


00490 


ADD 

A,E 


00500 


LD 

C, A 

;SAVE CHECKSUM 

00510 

LP2 

LD 

A, (HL) 


00520 


CALL 

0264H 

;OUTPUT DATA 

00530 


ADD 

A, C 


00540 


L0 

C, A 

{SAVE CHECKSUM 

00550 


INC 

HL 


00560 


DEC 

DE 


00570 


XOR 

A 


00580 


OR 

E 

;BLOCK END? 
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OUTPUT CHECKSUM 


00S90 

JR 

NZ,LP2 


00600 

LD 

A,C 


00610 

CALL 

026 4H 

;OUTPUT CHECKSUM 

00620 

EX 

DE,HL 


00630 

LD 

HL. (40F9H) 

;BAS 1C END ADDR 

00640 

PUSH 

DE 


006 50 

INC 

DE 


00660 

INC 

DE 


00670 

INC 

DE 


00680 

OR 

A 


00690 

SBC 

HL, DE 

;IS THIS THE END? 

00700 

POP 

HL 


00710 

JP 

P.LP1 

;N0 

00720 

LD 

A, 7 8H 

;EXECUTE SYNC 

00730 

CALL 

0264H 


00740 

LD 

A,0E9H 

;‘ENTRY POINT* 

00750 

CALL 

0264H 


00760 

LD 

A,42H 

;»ENTRY POINT* 

00770 

CALL 

0264H 


00780 

CALL 

01F8H 

;CASSETTE OFF 

00790 

JP 

1A19H 

;LEVEL II RETURN 

00800 TEXT 

DEFM 

'ENTER THE' 


00810 

DEEM 

' TITLE: ' 


00820 

DEFB 

0 


00830 

END 

START 
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APPENDIX 3 

A Program for Faster Recording of Data Tapes 


Data lists arc stored on tape with the BASIC command "PRINT# — 1, X". Each time this statement is 
encountered in the program, a new leader and sync byte are generated. The leader is 256 bytes long and takes 4 
seconds to write. The maximum number of bytes of data that may be written with one such command is also 256 
bytes. Thus, under the best conditions half of your tape I/O time is occupied with leader. Typically the leader 
requires an even greater proportion of the time. The assembly language routine given below will write a data 
tape with a short leader. The tape so written may be read back with the standard INPUT# —1 command. 
Because the operations are so fast, it is advisable to disable the automatic control of tape transport and start and 
stop the cassette manually. 

Before you can shorten the tape leaders, you must first write a normal length leader to allow the TRS—80 to 
lock onto your data signal. This may be accomplished by first writing a dummy value to the tape in the standard 
way (PRINT# — !, 0). Then, to activate the custom tape writing routine, use the following (compound) 
statement any place that you would normally use "PRINT# — !, A$": 


500 P%=0:P% = USR(VARPTR(A$)) 


The first statement ensures that the variable P% has been established in BASIC variable storage so that the 
pointer to the "dope" block of AS (as fetched by VARPTR) will be true when passed to the assembly language 
subroutine. The second statement calls the assembly language subroutine, which writes the string to tape. The 
"AS" may be replaced by any string name. To write a number to tape, first convert it to a string with the STRS 
function. To read it back, input it as a string and use the VAL function to convert it to a number again. It may be 
necessary to read all the numeric data before converting to numeric form because the VAL function is slow. 

■ The following source listing of the assembly language routine contains a linkage initialization segment; this 
routine has been designed to be the first segment of a composite program construted according to the directions 
given in Chapters 14 and 17. 


00100 


ORG 

42E9H 


00110 


LO 

HL,ENTRY 

,-LINKAGE 

00120 


LD 

(408EH),HL 

;1N1T1AL1ZATION 

-00130 


L0 

HL, FINIS 

;SEGMENT 

0011(0 


LD 

(4 0A4H ) , H L 


00150 


LD 

DE,65530 


00160 


CALL 

182CH 


00170 


INC 

HL 


00180 


INC 

HL 


00190 


LD 

(40F9H), HL 


00200 


LD 

HL,1D1EH 


00210 


PUSH 

HL 


00220 


JP 

1850H 


00230 

ENTRY 

LD 

8, 0 AH 

;LENGTH OF LEADER 

0021(0 

LOOP 

XOR 

A 

;LEADER BYTE - 0 

00250 


CALL 

0264H 

;WR1TE BYTE 

00260 


DJNZ 

LOOP 


00270 


LD 

A,0A5H 

;SYNC BYTE 

00280 


CALL 

0264H 


00290 


LD 

HL, ( 4121H ) 

;"DOPE” POINTER 

00300 


LO 

B, (HL) 

jSTRING LENGTH 

00310 


INC 

HL 


00320 


LD 

E, (HL) 

;STRING ADDRESS 
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00330 


INC 

HL 


00340 


L0 

D.(HL) 

;STR1NG ADDRESS 

00350 

WRITE 

LD 

A, (DE) 

.-NEXT CHARACTER 

00360 


CALL 

0264H 

;WR1TE TO TAPE 

003 70 


INC 

DE 


00380 


DJNZ 

WRITE 


00390 


LD 

A.0DH 

;END BYTE 

00400 


CALL 

0264H 


00410 


RET 



00420 


DEFB 

0 

;BASIC TEXT NEXT 

00430 

FINIS 

DEFS 

0 


00440 


END 




The following BASIC program (to be adjoined to the end of the above routine as explained in Chapter 17) is a 
demonstration program that will create 10 strings, dump them to tape with short leaders, and read them back. 
Note that the printing of a dummy variable requires reading in a dummy variable before the start of the actual 
data. 


100 CLEAR 100 
110 FOR 1-1 TO 10 

120 AS (I )-STRS(100 - I ): REM: GENERATE 10 STRINGS 

130 PRINT AS(I):NEXT I 

140 PRINT "PREPARE CASSETTE TO RECORD. THEN PRESS ENTER." 

ISO XS * INKEYS:IF XS-"" THEN 150 

160 PR I NT*-1,0: REM: WRITE DUMMY VARIABLE 

170 FOR 1-1 TO 10 

180 PRINT "WRITING NUMBER";I 

190 REM: BE SURE TO SET UP THE VARIABLE Pt FIRST 
200 Pt-0:Pt-USR(VARPTR(AS (I ))): REM: WRITE TO TAPE 

210 NEXT I 

220 PRINT "REWIND THE TAPE AND PRESS ENTER FOR PLAYBACK." 

230 XS-INKEYS:IF XS-"" THEN 230 

240 INPUT#-1,N: REM: INPUT DUMMY VARIABLE 

250 FOR 1-1 TO 10:INPUT#-1,AS(I) 

260 PRINT "READING NUMBER";I:NEXT I 
270 FOR l-l TO 10:PR I NT AS(t):NEXT I 
280 END 


Note that this system writes only one value for each tape command. If you are dealing exclusively with numeric 
variables — several of which can be written with each standard PRINT#— 1 statement — this technique may 
not be particularly advantageous. It is of greatest value when dealing with long string variables. 
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